Content Management API > Record

Unpublish a record

In a model where the draft/published system is enabled, Published records can subsequently be Unpublished in order to return them to Draft status.

When unpublishing a record, you can choose to either unpublish the whole record, or just some of its locales, similar to how the "Unpublish" dropdown button in the UI sidebar works.

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

This will unpublish the entire record, including all its localizations.

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

1
import { buildClient, inspectItem } from "@datocms/cma-client-node";
2
import type * as Schema from "./schema.js";
3

4
/*
5
 * BlogPost
6
 * ├─ title: string
7
 * └─ slug: slug
8
 */
9

10
async function run() {
11
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
12

13
  const itemId = "fyq6ADkeTL6Ryk7s98xmHw";
14

15
  // The record starts as Published. The attributes are the same before and
16
  // after unpublishing; what changes is the record's publication state,
17
  // which lives in `meta` (status / published_at).
18
  const beforeUnpublish = await client.items.find<Schema.BlogPost>(itemId);
19
  console.log("-- BEFORE UNPUBLISH --");
20
  console.log(`meta.status: "${beforeUnpublish.meta.status}"`);
21
  console.log(`meta.published_at: ${beforeUnpublish.meta.published_at}`);
22
  console.log(inspectItem(beforeUnpublish));
23

24
  const unpublishedItem = await client.items.unpublish<Schema.BlogPost>(itemId);
25

26
  console.log("-- AFTER UNPUBLISH --");
27
  console.log(`meta.status: "${unpublishedItem.meta.status}"`);
28
  console.log(`meta.published_at: ${unpublishedItem.meta.published_at}`);
29
  console.log(inspectItem(unpublishedItem));
30
}
31

32
run();

1
-- BEFORE UNPUBLISH --
2
meta.status: "published"
3
meta.published_at: 2026-04-23T10:02:26.737+01:00
4
└ Item "fyq6ADkeTL6Ryk7s98xmHw" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
5
  ├ title: "My first blog post!"
6
  └ slug: "my-first-blog-post"
7

8
-- AFTER UNPUBLISH --
9
meta.status: "draft"
10
meta.published_at: null
11
└ Item "fyq6ADkeTL6Ryk7s98xmHw" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
12
  ├ title: "My first blog post!"
13
  └ slug: "my-first-blog-post"

Selective unpublishing is used when you only want to unpublish certain localizations instead of the whole record.

Please note: You can only unpublish locales that are currently published within a specific record. If you try to unpublish a record's locale that is already unpublished (i.e. in draft state) or doesn't exist in the record at all (even if the project has that locale), you will get a VALIDATION_INVALID error on the content_in_locales field.

1
import { buildClient, inspectItem } from "@datocms/cma-client-node";
2
import type * as Schema from "./schema.js";
3

4
/*
5
 * BlogPost
6
 * ├─ title: string (localized)
7
 * └─ slug: slug
8
 */
9

10
async function run() {
11
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
12

13
  const itemId = "fyq6ADkeTL6Ryk7s98xmHw";
14

15
  // Read the current published version so we can compare it to the new
16
  // published version after the selective unpublish.
17
  const publishedBefore = await client.items.find<Schema.BlogPost>(itemId, {
18
    version: "published",
19
  });
20
  console.log("-- Published version BEFORE --");
21
  console.log(inspectItem(publishedBefore));
22

23
  // Unpublish only the `it` locale — the `en` locale and the non-localized
24
  // fields stay published.
25
  await client.items.unpublish<Schema.BlogPost>(itemId, {
26
    content_in_locales: ["it"],
27
  });
28

29
  // Re-read the published version: the `it` translation is gone; `en` and
30
  // `slug` are unchanged.
31
  const publishedAfter = await client.items.find<Schema.BlogPost>(itemId, {
32
    version: "published",
33
  });
34
  console.log("-- Published version AFTER --");
35
  console.log(inspectItem(publishedAfter));
36
}
37

38
run();

1
-- Published version BEFORE --
2
└ Item "fyq6ADkeTL6Ryk7s98xmHw" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
3
  ├ title
4
  │ ├ en: "My first blog post!"
5
  │ └ it: "Il mio primo post!"
6
  └ slug: "my-first-blog-post"
7

8
-- Published version AFTER --
9
└ Item "fyq6ADkeTL6Ryk7s98xmHw" (item_type: "UZyfjdBES8y2W2ruMEHSoA")
10
  ├ title
11
  │ └ en: "My first blog post!"
12
  └ slug: "my-first-blog-post"

TypeScript typing

Unpublishing 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.unpublish. 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.unpublish<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 children records are published, those children records will unpublished as well. When recursive is false or not specified, a PUBLISHED_CHILDREN error will occur in such cases.

Body parameters

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

content_in_locales Required

Array of locales to publish. They must be currently published in this record. To unpublish all locales, do NOT use this parameter, but instead unpublish the entire record by leaving the body blank (see example above).

Type: Array<string>

Examples:

["en"]

["en", "it"]

Returns

Returns a resource object of type item