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)

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
});

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

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
  "data": {
9
    "id": "fyq6ADkeTL6Ryk7s98xmHw",
10
    "type": "item",
11
    "attributes": {
12
      "title": {
13
        "en": "Example",
14
        "es": "Ejemplo",
15
        "fr": "Exemple",
16
        "it": "Esempio"
17
      }
18
    },
19
    "relationships": {
20
      "item_type": {
21
        "data": {
22
          "id": "AKjM7INpQQ-51l9WmwF1VA",
23
          "type": "item_type"
24
        }
25
      },
26
      "creator": {
27
        "data": {
28
          "id": "627975",
29
          "type": "organization"
30
        }
31
      }
32
    },
33
    "meta": {
34
      "created_at": "2024-01-09T23:47:27.792+00:00",
35
      "updated_at": "2024-01-09T23:52:03.787+00:00",
36
      "published_at": null,
37
      "publication_scheduled_at": null,
38
      "unpublishing_scheduled_at": null,
39
      "first_published_at": "2024-01-09T23:48:41.998+00:00",
40
      "is_valid": true,
41
      "is_current_version_valid": true,
42
      "is_published_version_valid": null,
43
      "status": "draft",
44
      "current_version": "CRpPrguuRe2tgZmBNsluUA",
45
      "stage": null
46
    }
47
  },
48
  "included": [
49
    {
50
      "id": "AKjM7INpQQ-51l9WmwF1VA",
51
      "type": "item_type",
52
      "attributes": {
53
        "name": "Post",
54
        "singleton": false,
55
        "sortable": false,
56
        "api_key": "post",
57
        "ordering_direction": null,
58
        "ordering_meta": null,
59
        "tree": false,
60
        "modular_block": false,
61
        "draft_mode_active": true,
62
        "all_locales_required": false,
63
        "collection_appearance": "table",
64
        "has_singleton_item": false,
65
        "hint": null,
66
        "inverse_relationships_enabled": false
67
      },
68
      "relationships": {
69
        "fields": {
70
          "data": [
71
            {
72
              "id": "blxA9kZ_SRi1yexMeTDg6g",
73
              "type": "field"
74
            }
75
          ]
76
        },
77
        "fieldsets": {
78
          "data": []
79
        },
80
        "singleton_item": {
81
          "data": null
82
        },
83
        "ordering_field": {
84
          "data": null
85
        },
86
        "title_field": {
87
          "data": {
88
            "id": "blxA9kZ_SRi1yexMeTDg6g",
89
            "type": "field"
90
          }
91
        },
92
        "image_preview_field": {
93
          "data": null
94
        },
95
        "excerpt_field": {
96
          "data": null
97
        },
98
        "workflow": {
99
          "data": null
100
        }
101
      },
102
      "meta": {
103
        "has_singleton_item": false
104
      }
105
    }
106
  ]
107
}

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

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_unpublish_operation",
10
    "attributes": {
11
      "content_in_locales": [
12
        "it"
13
      ]
14
    }
15
  }
16
}

Unpublishing only the "it" 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_unpublish_operation","attributes":{"content_in_locales":["it"]}}}'

Unpublishing only the "it" 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_unpublish_operation",
12
      attributes: { content_in_locales: ["it"] },
13
    },
14
  }),
15
});

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

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
  "data": {
9
    "id": "fyq6ADkeTL6Ryk7s98xmHw",
10
    "type": "item",
11
    "attributes": {
12
      "title": {
13
        "en": "Example",
14
        "es": "Ejemplo",
15
        "it": "Esempio"
16
      }
17
    },
18
    "relationships": {
19
      "item_type": {
20
        "data": {
21
          "id": "AKjM7INpQQ-51l9WmwF1VA",
22
          "type": "item_type"
23
        }
24
      },
25
      "creator": {
26
        "data": {
27
          "id": "627975",
28
          "type": "organization"
29
        }
30
      }
31
    },
32
    "meta": {
33
      "created_at": "2024-01-09T23:47:27.792+00:00",
34
      "updated_at": "2024-01-09T23:48:40.994+00:00",
35
      "published_at": "2024-01-09T23:49:06.801+00:00",
36
      "publication_scheduled_at": null,
37
      "unpublishing_scheduled_at": null,
38
      "first_published_at": "2024-01-09T23:48:41.998+00:00",
39
      "is_valid": true,
40
      "is_current_version_valid": true,
41
      "is_published_version_valid": true,
42
      "status": "updated",
43
      "current_version": "JkXS--AoQyyosXo8q5m1mQ",
44
      "stage": null
45
    }
46
  },
47
  "included": [
48
    {
49
      "id": "AKjM7INpQQ-51l9WmwF1VA",
50
      "type": "item_type",
51
      "attributes": {
52
        "name": "Post",
53
        "singleton": false,
54
        "sortable": false,
55
        "api_key": "post",
56
        "ordering_direction": null,
57
        "ordering_meta": null,
58
        "tree": false,
59
        "modular_block": false,
60
        "draft_mode_active": true,
61
        "all_locales_required": false,
62
        "collection_appearance": "table",
63
        "has_singleton_item": false,
64
        "hint": null,
65
        "inverse_relationships_enabled": false
66
      },
67
      "relationships": {
68
        "fields": {
69
          "data": [
70
            {
71
              "id": "blxA9kZ_SRi1yexMeTDg6g",
72
              "type": "field"
73
            }
74
          ]
75
        },
76
        "fieldsets": {
77
          "data": []
78
        },
79
        "singleton_item": {
80
          "data": null
81
        },
82
        "ordering_field": {
83
          "data": null
84
        },
85
        "title_field": {
86
          "data": {
87
            "id": "blxA9kZ_SRi1yexMeTDg6g",
88
            "type": "field"
89
          }
90
        },
91
        "image_preview_field": {
92
          "data": null
93
        },
94
        "excerpt_field": {
95
          "data": null
96
        },
97
        "workflow": {
98
          "data": null
99
        }
100
      },
101
      "meta": {
102
        "has_singleton_item": false
103
      }
104
    }
105
  ]
106
}

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.

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.