Sorry, no results found for "".

Show examples in:
Javascript HTTP

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 {}.

(No request body)

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

(No request body)

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

(No request body)

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

Note that data.meta.is_published_version_valid === null because the entire record has been unpublished.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: cache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
{
"data": {
"id": "fyq6ADkeTL6Ryk7s98xmHw",
"type": "item",
"attributes": {
"title": {
"en": "Example",
"es": "Ejemplo",
"fr": "Exemple",
"it": "Esempio"
}
},
"relationships": {
"item_type": {
"data": {
"id": "AKjM7INpQQ-51l9WmwF1VA",
"type": "item_type"
}
},
"creator": {
"data": {
"id": "627975",
"type": "organization"
}
}
},
"meta": {
"created_at": "2024-01-09T23:47:27.792+00:00",
"updated_at": "2024-01-09T23:52:03.787+00:00",
"published_at": null,
"publication_scheduled_at": null,
"unpublishing_scheduled_at": null,
"first_published_at": "2024-01-09T23:48:41.998+00:00",
"is_valid": true,
"is_current_version_valid": true,
"is_published_version_valid": null,
"status": "draft",
"current_version": "CRpPrguuRe2tgZmBNsluUA",
"stage": null
}
},
"included": [
{
"id": "AKjM7INpQQ-51l9WmwF1VA",
"type": "item_type",
"attributes": {
"name": "Post",
"singleton": false,
"sortable": false,
"api_key": "post",
"ordering_direction": null,
"ordering_meta": null,
"tree": false,
"modular_block": false,
"draft_mode_active": true,
"all_locales_required": false,
"collection_appearance": "table",
"has_singleton_item": false,
"hint": null,
"inverse_relationships_enabled": false
},
"relationships": {
"fields": {
"data": [
{
"id": "blxA9kZ_SRi1yexMeTDg6g",
"type": "field"
}
]
},
"fieldsets": {
"data": []
},
"singleton_item": {
"data": null
},
"ordering_field": {
"data": null
},
"title_field": {
"data": {
"id": "blxA9kZ_SRi1yexMeTDg6g",
"type": "field"
}
},
"image_preview_field": {
"data": null
},
"excerpt_field": {
"data": null
},
"workflow": {
"data": null
}
},
"meta": {
"has_singleton_item": false
}
}
]
}

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.

Unpublishing only the "it" locale

PUT https://site-api.datocms.com/items/:item_id/publish HTTP/1.1
Authorization: Bearer YOUR-API-TOKEN
Accept: application/json
X-Api-Version: 3
Content-Type: application/vnd.api+json
{
"data": {
"type": "selective_unpublish_operation",
"attributes": {
"content_in_locales": [
"it"
]
}
}
}

Unpublishing only the "it" locale

Terminal window
curl -g 'https://site-api.datocms.com/items/:item_id/publish' \
-X PUT \
-H "Authorization: Bearer YOUR-API-TOKEN" \
-H "Accept: application/json" \
-H "X-Api-Version: 3" \
-H "Content-Type: application/vnd.api+json" \
--data-binary '{"data":{"type":"selective_unpublish_operation","attributes":{"content_in_locales":["it"]}}}'

Unpublishing only the "it" locale

await fetch("https://site-api.datocms.com/items/:item_id/publish", {
method: "PUT",
headers: {
Authorization: "Bearer YOUR-API-TOKEN",
Accept: "application/json",
"X-Api-Version": "3",
"Content-Type": "application/vnd.api+json",
},
body: JSON.stringify({
data: {
type: "selective_unpublish_operation",
attributes: { content_in_locales: ["it"] },
},
}),
});

Note that data.meta.is_published_version_valid === true because the rest of the record is still published.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: cache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
{
"data": {
"id": "fyq6ADkeTL6Ryk7s98xmHw",
"type": "item",
"attributes": {
"title": {
"en": "Example",
"es": "Ejemplo",
"it": "Esempio"
}
},
"relationships": {
"item_type": {
"data": {
"id": "AKjM7INpQQ-51l9WmwF1VA",
"type": "item_type"
}
},
"creator": {
"data": {
"id": "627975",
"type": "organization"
}
}
},
"meta": {
"created_at": "2024-01-09T23:47:27.792+00:00",
"updated_at": "2024-01-09T23:48:40.994+00:00",
"published_at": "2024-01-09T23:49:06.801+00:00",
"publication_scheduled_at": null,
"unpublishing_scheduled_at": null,
"first_published_at": "2024-01-09T23:48:41.998+00:00",
"is_valid": true,
"is_current_version_valid": true,
"is_published_version_valid": true,
"status": "updated",
"current_version": "JkXS--AoQyyosXo8q5m1mQ",
"stage": null
}
},
"included": [
{
"id": "AKjM7INpQQ-51l9WmwF1VA",
"type": "item_type",
"attributes": {
"name": "Post",
"singleton": false,
"sortable": false,
"api_key": "post",
"ordering_direction": null,
"ordering_meta": null,
"tree": false,
"modular_block": false,
"draft_mode_active": true,
"all_locales_required": false,
"collection_appearance": "table",
"has_singleton_item": false,
"hint": null,
"inverse_relationships_enabled": false
},
"relationships": {
"fields": {
"data": [
{
"id": "blxA9kZ_SRi1yexMeTDg6g",
"type": "field"
}
]
},
"fieldsets": {
"data": []
},
"singleton_item": {
"data": null
},
"ordering_field": {
"data": null
},
"title_field": {
"data": {
"id": "blxA9kZ_SRi1yexMeTDg6g",
"type": "field"
}
},
"image_preview_field": {
"data": null
},
"excerpt_field": {
"data": null
},
"workflow": {
"data": null
}
},
"meta": {
"has_singleton_item": false
}
}
]
}

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.
type string Required

Must be exactly "selective_unpublish_operation".

attributes.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.