Content Management API > Record

Publish a record

When the draft/published system is enabled for a model, records will remain in a Draft status until they are Published.

When publishing a record, you can choose to either publish the whole record, or just some of its locales / non-localized content. This is similar to how the "Publish" dropdown button in the UI works.

This is the default behavior when you don't provide a request body.

This will publish the entire record, including all its localized and non-localized fields.

Do not include a request body at all — not even an empty object {}.

(No request body)

1
PUT https://site-api.datocms.com/items/:item_id/publish HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3
5
Content-Type: application/vnd.api+json

(No request body)

1
curl -g 'https://site-api.datocms.com/items/:item_id/publish' \
2
  -X PUT \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3" \
6
  -H "Content-Type: application/vnd.api+json"

(No request body)

1
await fetch("https://site-api.datocms.com/items/:item_id/publish", {
2
  method: "PUT",
3
  headers: {
4
    Authorization: "Bearer YOUR-API-TOKEN",
5
    Accept: "application/json",
6
    "X-Api-Version": "3",
7
    "Content-Type": "application/vnd.api+json",
8
  },
9
});

Published item:

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
{
8
  "id": "WxrWMPl3TjeSJYcl6lNCbg",
9
  "type": "item",
10
  "localized_title": {
11
    "en": "New English title",
12
    "es": "New Spanish title",
13
    "it": "New Italian title"
14
  },
15
  "non_localized_field": "New lorem ipsum",
16
  "item_type": {
17
    "id": "CcW1FAf4Sd20dAZijsbzuQ",
18
    "type": "item_type"
19
  },
20
  "creator": {
21
    "id": "627975",
22
    "type": "organization"
23
  },
24
  "meta": {
25
    "created_at": "2024-01-04T23:02:07.204+00:00",
26
    "updated_at": "2024-01-04T23:03:53.121+00:00",
27
    "published_at": "2024-01-04T23:03:21.566+00:00",
28
    "publication_scheduled_at": null,
29
    "unpublishing_scheduled_at": null,
30
    "first_published_at": "2024-01-04T23:03:21.566+00:00",
31
    "is_valid": true,
32
    "is_current_version_valid": true,
33
    "is_published_version_valid": true,
34
    "status": "updated",
35
    "current_version": "WEU_H0i2S8mkaV7ML8OTqw",
36
    "stage": null
37
  }
38
}

Selective publishing is used when you don't want to publish the entire record. Instead, you can publish a combination of:

Zero or more specified locales
And/or all of this record's non-localized fields

In this example, we will only publish the en locale. The it and es versions of localized_title will not be published, and will retain their previously published titles. non_localized_field will also keep its previously published value.

Publishing only the "en" locale

1
PUT https://site-api.datocms.com/items/:item_id/publish HTTP/1.1
2
Authorization: Bearer YOUR-API-TOKEN
3
Accept: application/json
4
X-Api-Version: 3
5
Content-Type: application/vnd.api+json
6

7
{
8
  "data": {
9
    "type": "selective_publish_operation",
10
    "attributes": {
11
      "content_in_locales": [
12
        "en"
13
      ],
14
      "non_localized_content": false
15
    }
16
  }
17
}

Publishing only the "en" locale

1
curl -g 'https://site-api.datocms.com/items/:item_id/publish' \
2
  -X PUT \
3
  -H "Authorization: Bearer YOUR-API-TOKEN" \
4
  -H "Accept: application/json" \
5
  -H "X-Api-Version: 3" \
6
  -H "Content-Type: application/vnd.api+json" \
7
  --data-binary '{"data":{"type":"selective_publish_operation","attributes":{"content_in_locales":["en"],"non_localized_content":false}}}'

Publishing only the "en" locale

1
await fetch("https://site-api.datocms.com/items/:item_id/publish", {
2
  method: "PUT",
3
  headers: {
4
    Authorization: "Bearer YOUR-API-TOKEN",
5
    Accept: "application/json",
6
    "X-Api-Version": "3",
7
    "Content-Type": "application/vnd.api+json",
8
  },
9
  body: JSON.stringify({
10
    data: {
11
      type: "selective_publish_operation",
12
      attributes: { content_in_locales: ["en"], non_localized_content: false },
13
    },
14
  }),
15
});

Published item with new English title. The Italian localized field and non-localized slug remain unchanged.

1
HTTP/1.1 200 OK
2
Content-Type: application/json
3
Cache-Control: cache-control: max-age=0, private, must-revalidate
4
X-RateLimit-Limit: 30
5
X-RateLimit-Remaining: 28
6

7
{
8
  "id": "WxrWMPl3TjeSJYcl6lNCbg",
9
  "type": "item",
10
  "localized_title": {
11
    "en": "New English title",
12
    "es": "Old Spanish title",
13
    "it": "Old Italian title"
14
  },
15
  "non_localized_field": "Old lorem ipsum",
16
  "item_type": {
17
    "id": "CcW1FAf4Sd20dAZijsbzuQ",
18
    "type": "item_type"
19
  },
20
  "creator": {
21
    "id": "627975",
22
    "type": "organization"
23
  },
24
  "meta": {
25
    "created_at": "2024-01-04T23:02:07.204+00:00",
26
    "updated_at": "2024-01-04T23:03:53.121+00:00",
27
    "published_at": "2024-01-04T23:03:21.566+00:00",
28
    "publication_scheduled_at": null,
29
    "unpublishing_scheduled_at": null,
30
    "first_published_at": "2024-01-04T23:03:21.566+00:00",
31
    "is_valid": true,
32
    "is_current_version_valid": true,
33
    "is_published_version_valid": true,
34
    "status": "updated",
35
    "current_version": "WEU_H0i2S8mkaV7ML8OTqw",
36
    "stage": null
37
  }
38
}

Query parameters

recursive boolean

When recursive is true, if the record belongs to a tree-like collection, and any of the parent records aren't published, those parent records will published as well. When recursive is false or not specified, an UNPUBLISHED_PARENT error will occur in such cases.

Body parameters

For this endpoint, the body is not required and can be entirely omitted.

type string Required

Must be exactly "selective_publish_operation". Publish only the specified locales & non-localized content (see following attributes). To publish the entire record, simply avoid passing a request body to the endpoint.

attributes.content_in_locales Required

Array of valid locale codes in this project to publish.

Type: Array<string>

Examples:

["en"]

["en", "it"]

attributes.non_localized_content boolean Required

Whether non-localized content will be published

Returns

Returns a resource object of type item.

Did this doc help you?

Need help?

Explore our forum, contact support, or connect with our sales team . You can also chat live with other users in our Slack channel.