REST API: status and hasPublishedVersion

The REST API offers the ability to filter results based on their status, draft or published, and by whether they have a published version.

Prerequisites

The Draft & Publish feature should be enabled.

status

Queries can accept a status parameter to fetch documents based on their status:

• published: returns only the published version of documents (default)
• draft: returns only the draft version of documents

Tip

In the response data, the publishedAt field is null for drafts.

Note

Since published versions are returned by default, passing no status parameter is equivalent to passing status=published.

Get draft versions of restaurants

GET /api/articles?status=draft

JavaScript query (built with the qs library):

The query URL above was built using the `qs` library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  status: 'draft',
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/articles?${query}`);

Example response

{
  "data": [
    // …
    {
      "id": 5,
      "documentId": "znrlzntu9ei5onjvwfaalu2v",
      "Name": "Biscotte Restaurant",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "This is the draft version."
            }
          ]
        }
      ],
      "createdAt": "2024-03-06T13:43:30.172Z",
      "updatedAt": "2024-03-06T21:38:46.353Z",
      "publishedAt": null,
      "locale": "en"
    },
    // …
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 4
    }
  }
}

hasPublishedVersion NewThis content is new.

Queries can accept a hasPublishedVersion parameter to filter documents by whether a published version exists. Use hasPublishedVersion with status=draft to distinguish documents that have never been published from drafts of already-published documents.

• hasPublishedVersion=false: returns only documents that have never been published
• hasPublishedVersion=true: returns only drafts of documents that have a published version

Get drafts that have never been published

GET /api/articles?status=draft&hasPublishedVersion=false

JavaScript query (built with the qs library):

The query URL above was built using the `qs` library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  status: 'draft',
  hasPublishedVersion: false,
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/articles?${query}`);

Example response

{
  "data": [
    {
      "id": 8,
      "documentId": "ln1gkzs6ojl9d707xn6v86mw",
      "Name": "Restaurant B",
      "createdAt": "2024-03-06T13:43:30.172Z",
      "updatedAt": "2024-03-06T21:38:46.353Z",
      "publishedAt": null,
      "locale": "en"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 1
    }
  }
}

Get drafts of already-published documents

GET /api/articles?status=draft&hasPublishedVersion=true

JavaScript query (built with the qs library):

The query URL above was built using the `qs` library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  status: 'draft',
  hasPublishedVersion: true,
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/articles?${query}`);

Example response

{
  "data": [
    {
      "id": 5,
      "documentId": "znrlzntu9ei5onjvwfaalu2v",
      "Name": "Biscotte Restaurant",
      "createdAt": "2024-03-06T13:43:30.172Z",
      "updatedAt": "2024-03-06T21:38:46.353Z",
      "publishedAt": null,
      "locale": "en"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 1
    }
  }
}

Note

Because the draft version is returned, publishedAt is null even when a published version exists.

Caution

Passing an invalid value for hasPublishedVersion (anything other than true or false) returns a 400 Bad Request error.