REST API: status

Page summary:

The REST API's status parameter returns either published versions (default) or drafts by passing status=draft.

It also applies to write requests: a POST or PUT request publishes immediately unless you pass status=draft.

The REST API offers the ability to work with the draft or the published version of documents through the status parameter:

• published: targets the published version of documents (default)
• draft: targets the draft version of documents

Prerequisites

The Draft & Publish feature should be enabled.

Note

The REST API defaults to published for every request, including POST and PUT requests. This differs from the Document Service API, which defaults to draft.

To select documents by how their draft and published versions relate (never-published, modified, and others), see REST API: publicationFilter.

Read draft or published versions

Add the status parameter to a GET request to choose which version is returned.

Tip

In the response data, the publishedAt field is null in the returned draft, even when a published version exists.

Note

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

GET/api/restaurants?status=draft

Get draft versions of restaurants

Returns draft versions of documents by passing the status=draft query parameter.

cURL

terminal

curl 'http://localhost:1337/api/restaurants?status=draft' \
  -H 'Authorization: Bearer <token>'

JavaScript

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

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

200 OK

{
  "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": 1
    }
  }
}

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.

Create or update as a draft or as published

The status parameter also applies to POST and PUT requests, where it determines whether the document is left as a draft or published right away:

Request	Result
POST /api/:pluralApiId?status=draft	Creates a draft document
POST /api/:pluralApiId	Creates a document and publishes it immediately
PUT /api/:pluralApiId/:documentId?status=draft	Updates the draft without publishing the changes
PUT /api/:pluralApiId/:documentId	Updates the draft and publishes it
PUT /api/:pluralApiId/:documentId with an empty data object	Publishes the draft as-is, without changing its content

The same applies to single types, where the status parameter can be passed to PUT /api/:singularApiId.

Note

With Draft & Publish enabled, the REST API defaults to status=published, so a POST or PUT request that does not include the status parameter publishes the document immediately. Pass status=draft explicitly to create or update content without publishing it.

Note

Published documents always keep a draft counterpart. Creating or updating a document with status=published writes the draft first, then publishes it, so both versions hold the same data.

Create a draft

POST/api/restaurants?status=draft

Create a draft document

Creates a new document and leaves it as a draft by passing the status=draft query parameter.

cURL

terminal

curl -X POST \
  'http://localhost:1337/api/restaurants?status=draft' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Name": "Biscotte Restaurant"
    }
  }'

JavaScript

const response = await fetch(
  'http://localhost:1337/api/restaurants?status=draft',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        Name: 'Biscotte Restaurant',
      },
    }),
  }
);
const data = await response.json();

201 Created

{
  "data": {
    "id": 13,
    "documentId": "jae8klabhuucbkgfe2xxc5dj",
    "Name": "Biscotte Restaurant",
    "createdAt": "2024-03-06T22:19:54.646Z",
    "updatedAt": "2024-03-06T22:19:54.646Z",
    "publishedAt": null,
    "locale": "en"
  },
  "meta": {}
}

The publishedAt field is null, which confirms the document was created as a draft.

Create and publish immediately

Omitting the status parameter, or passing status=published, creates the document and publishes it in a single request:

POST/api/restaurants

Create and publish a document

Creates a new document and publishes it immediately, which is the default behavior of the REST API.

cURL

terminal

curl -X POST \
  'http://localhost:1337/api/restaurants' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Name": "Biscotte Restaurant"
    }
  }'

JavaScript

const response = await fetch(
  'http://localhost:1337/api/restaurants',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        Name: 'Biscotte Restaurant',
      },
    }),
  }
);
const data = await response.json();

201 Created

{
  "data": {
    "id": 13,
    "documentId": "jae8klabhuucbkgfe2xxc5dj",
    "Name": "Biscotte Restaurant",
    "createdAt": "2024-03-06T22:19:54.646Z",
    "updatedAt": "2024-03-06T22:19:54.646Z",
    "publishedAt": "2024-03-06T22:19:54.649Z",
    "locale": "en"
  },
  "meta": {}
}

Here publishedAt holds a timestamp instead of null, which confirms the document was published.

Update a draft without publishing it

Pass status=draft to a PUT request to modify the draft version and leave the published version untouched:

PUT/api/restaurants/:documentId?status=draft

Update a draft document

Updates the draft version of a document without publishing the changes.

cURL

terminal

curl -X PUT \
  'http://localhost:1337/api/restaurants/jae8klabhuucbkgfe2xxc5dj?status=draft' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Name": "Biscotte Restaurant (closed)"
    }
  }'

JavaScript

const response = await fetch(
  'http://localhost:1337/api/restaurants/jae8klabhuucbkgfe2xxc5dj?status=draft',
  {
    method: 'PUT',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        Name: 'Biscotte Restaurant (closed)',
      },
    }),
  }
);
const data = await response.json();

200 OK

{
  "data": {
    "id": 13,
    "documentId": "jae8klabhuucbkgfe2xxc5dj",
    "Name": "Biscotte Restaurant (closed)",
    "createdAt": "2024-03-06T22:19:54.646Z",
    "updatedAt": "2024-03-06T22:24:12.145Z",
    "publishedAt": null,
    "locale": "en"
  },
  "meta": {}
}

Publish an existing draft

To publish a draft created earlier, send a PUT request without the status parameter, or with status=published:

PUT/api/restaurants/:documentId

Publish an existing draft

Publishes the draft version of a document, which is the default behavior of PUT requests.

cURL

terminal

curl -X PUT \
  'http://localhost:1337/api/restaurants/jae8klabhuucbkgfe2xxc5dj' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "Name": "Biscotte Restaurant (closed)"
    }
  }'

JavaScript

const response = await fetch(
  'http://localhost:1337/api/restaurants/jae8klabhuucbkgfe2xxc5dj',
  {
    method: 'PUT',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {
        Name: 'Biscotte Restaurant (closed)',
      },
    }),
  }
);
const data = await response.json();

200 OK

{
  "data": {
    "id": 13,
    "documentId": "jae8klabhuucbkgfe2xxc5dj",
    "Name": "Biscotte Restaurant (closed)",
    "createdAt": "2024-03-06T22:19:54.646Z",
    "updatedAt": "2024-03-06T22:26:38.902Z",
    "publishedAt": "2024-03-06T22:26:38.905Z",
    "locale": "en"
  },
  "meta": {}
}

A PUT request requires a data object in the body, so the request above updates and publishes in a single operation.

Publish a draft without changing its content

To publish a draft as-is, send a PUT request with an empty data object:

PUT/api/restaurants/:documentId

Publish a draft without changing its content

Publishes the draft version of a document as-is by sending an empty data object.

cURL

terminal

curl -X PUT \
  'http://localhost:1337/api/restaurants/jae8klabhuucbkgfe2xxc5dj' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {}
  }'

JavaScript

const response = await fetch(
  'http://localhost:1337/api/restaurants/jae8klabhuucbkgfe2xxc5dj',
  {
    method: 'PUT',
    headers: {
      Authorization: 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      data: {},
    }),
  }
);
const data = await response.json();

200 OK

{
  "data": {
    "id": 13,
    "documentId": "jae8klabhuucbkgfe2xxc5dj",
    "Name": "Biscotte Restaurant (closed)",
    "createdAt": "2024-03-06T22:19:54.646Z",
    "updatedAt": "2024-03-06T22:26:38.902Z",
    "publishedAt": "2024-03-06T22:31:14.207Z",
    "locale": "en"
  },
  "meta": {}
}

Note

Omitting the data key entirely returns a 400 error, so send "data": {} rather than an empty body.