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
-- BEFORE PUBLISH --
8
meta.status: "draft"
9
meta.published_at: null
10
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
11
  ├ title: "My first blog post!"
12
  └ slug: "my-first-blog-post"
13

14
-- AFTER PUBLISH --
15
meta.status: "published"
16
meta.published_at: 2026-04-23T10:02:27.599+01:00
17
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
18
  ├ title: "My first blog post!"
19
  └ slug: "my-first-blog-post"

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
-- Published version BEFORE --
8
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
9
  ├ title
10
  │ ├ en: "My first blog post!"
11
  │ └ it: "Il mio primo post!"
12
  └ slug: "my-first-blog-post"
13

14
-- Published version AFTER --
15
└ Item "T4m4tPymSACFzsqbZS65WA" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
16
  ├ title
17
  │ ├ en: "My first blog post! (updated)"
18
  │ └ it: "Il mio primo post!"
19
  └ slug: "my-first-blog-post"

TypeScript typing

Publishing a record without typed schemas gives you back a record whose attributes are all unknown — any downstream code that reads from it is fighting TypeScript. The single biggest lever you have is passing a generated Schema.X marker as the generic on items.publish. TypeScript then knows the exact shape of the returned record — its field names, types, and block structures — so reads are typed end-to-end:

1
import * as Schema from "./schema";
2

3
const record = await client.items.publish<Schema.Article>("record-id");
4
record.title; // typed, not unknown

For the exact type of a specific field on the returned record (to annotate a helper or intermediate variable), index ApiTypes.Item<Schema.Article>["field_api_key"]. See the full TypeScript guide for how to generate schema.ts and the complete pattern.

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.

Publish a record

HTTP Request

CURL Request

fetch() Request

HTTP Response

HTTP Request

CURL Request

fetch() Request

HTTP Response

TypeScript typing

Query parameters

Body parameters

Returns