You're reading "Content Management API"

Record

DatoCMS stores the individual pieces of content you create from a model as records, which are much like table rows in a database. For backward-compatibility reasons, the API refers to records as "items".

List all records

To list all records, send a GET request to the /items endpoint. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
GET https://site-api.datocms.com/items HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": [ { "type": "item", "id": "4235", "attributes": { "title": "My first blog post!", "content": "Lorem ipsum dolor sit amet...", "category": "24", "image": "1235" }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } }, "creator": { "data": { "type": "account", "id": "312" } } }, "meta": { "created_at": "", "updated_at": "", "published_at": null, "first_published_at": null, "publication_scheduled_at": null, "status": null, "is_valid": true } } ], "meta": { "total_count": 20 } }

Retrieve a record

To retrieve a record, send a GET request to the /items/:item_id endpoint. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
GET https://site-api.datocms.com/items/:item_id HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "item", "id": "4235", "attributes": { "title": "My first blog post!", "content": "Lorem ipsum dolor sit amet...", "category": "24", "image": "1235" }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } }, "creator": { "data": { "type": "account", "id": "312" } } }, "meta": { "created_at": "", "updated_at": "", "published_at": null, "first_published_at": null, "publication_scheduled_at": null, "status": null, "is_valid": true } } }

Create a new record

To create a new record, send a POST request to the /items endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
POST https://site-api.datocms.com/items HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Content-Typeapplication/json
{ "data": { "type": "item", "attributes": { "title": "My first blog post!", "content": "Lorem ipsum dolor sit amet...", "category": "24", "image": "1235" }, "meta": {}, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } } } } }
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "item", "id": "4235", "attributes": { "title": "My first blog post!", "content": "Lorem ipsum dolor sit amet...", "category": "24", "image": "1235" }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } }, "creator": { "data": { "type": "account", "id": "312" } } }, "meta": { "created_at": "", "updated_at": "", "published_at": null, "first_published_at": null, "publication_scheduled_at": null, "status": null, "is_valid": true } }, "included": [ { "type": "item_type", "id": "44", "attributes": { "name": "Blog post", "api_key": "post", "collection_appeareance": "compact", "singleton": false, "all_locales_required": false, "sortable": true, "modular_block": false, "draft_mode_active": false, "tree": false, "ordering_direction": null, "has_singleton_item": true }, "relationships": { "menu_item": { "data": null }, "singleton_item": { "data": null }, "fields": { "data": [ { "type": "field", "id": "124" } ] }, "title_field": { "data": null }, "ordering_field": { "data": null } } } ] }

Update a record

To update a record, send a PUT request to the /items/:item_id endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
PUT https://site-api.datocms.com/items/:item_id HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Content-Typeapplication/json
{ "data": { "type": "item", "id": "4235", "attributes": { "title": "My first blog post!", "content": "Lorem ipsum dolor sit amet...", "category": "24", "image": "1235" }, "relationships": { "creator": { "data": { "type": "account", "id": "312" } } } } }
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "item", "id": "4235", "attributes": { "title": "My first blog post!", "content": "Lorem ipsum dolor sit amet...", "category": "24", "image": "1235" }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } }, "creator": { "data": { "type": "account", "id": "312" } } }, "meta": { "created_at": "", "updated_at": "", "published_at": null, "first_published_at": null, "publication_scheduled_at": null, "status": null, "is_valid": true } }, "included": [ { "type": "item", "id": "4235", "attributes": { "title": "My first blog post!", "content": "Lorem ipsum dolor sit amet...", "category": "24", "image": "1235" }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } }, "creator": { "data": { "type": "account", "id": "312" } } }, "meta": { "created_at": "", "updated_at": "", "published_at": null, "first_published_at": null, "publication_scheduled_at": null, "status": null, "is_valid": true } } ] }

Delete a record

To delete a record, send a DELETE request to the /items/:item_id endpoint. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
DELETE https://site-api.datocms.com/items/:item_id HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "item", "id": "4235", "attributes": { "title": "My first blog post!", "content": "Lorem ipsum dolor sit amet...", "category": "24", "image": "1235" }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } }, "creator": { "data": { "type": "account", "id": "312" } } }, "meta": { "created_at": "", "updated_at": "", "published_at": null, "first_published_at": null, "publication_scheduled_at": null, "status": null, "is_valid": true } } }

Duplicate a record

To duplicate a record, send a POST request to the /items/:item_id/duplicate endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
POST https://site-api.datocms.com/items/:item_id/duplicate HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "item", "id": "4235", "attributes": { "title": "My first blog post!", "content": "Lorem ipsum dolor sit amet...", "category": "24", "image": "1235" }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } }, "creator": { "data": { "type": "account", "id": "312" } } }, "meta": { "created_at": "", "updated_at": "", "published_at": null, "first_published_at": null, "publication_scheduled_at": null, "status": null, "is_valid": true } }, "meta": {}, "included": [ { "type": "item_type", "id": "44", "attributes": { "name": "Blog post", "api_key": "post", "collection_appeareance": "compact", "singleton": false, "all_locales_required": false, "sortable": true, "modular_block": false, "draft_mode_active": false, "tree": false, "ordering_direction": null, "has_singleton_item": true }, "relationships": { "menu_item": { "data": null }, "singleton_item": { "data": null }, "fields": { "data": [ { "type": "field", "id": "124" } ] }, "title_field": { "data": null }, "ordering_field": { "data": null } } } ] }

Publish a record

To publish a record, send a PUT request to the /items/:item_id/publish endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
PUT https://site-api.datocms.com/items/:item_id/publish HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "item", "id": "4235", "attributes": { "title": "My first blog post!", "content": "Lorem ipsum dolor sit amet...", "category": "24", "image": "1235" }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } }, "creator": { "data": { "type": "account", "id": "312" } } }, "meta": { "created_at": "", "updated_at": "", "published_at": null, "first_published_at": null, "publication_scheduled_at": null, "status": null, "is_valid": true } }, "included": [ { "type": "item_type", "id": "44", "attributes": { "name": "Blog post", "api_key": "post", "collection_appeareance": "compact", "singleton": false, "all_locales_required": false, "sortable": true, "modular_block": false, "draft_mode_active": false, "tree": false, "ordering_direction": null, "has_singleton_item": true }, "relationships": { "menu_item": { "data": null }, "singleton_item": { "data": null }, "fields": { "data": [ { "type": "field", "id": "124" } ] }, "title_field": { "data": null }, "ordering_field": { "data": null } } } ] }

Unpublish a record

To unpublish a record, send a PUT request to the /items/:item_id/unpublish endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.

Example request
PUT https://site-api.datocms.com/items/:item_id/unpublish HTTP/1.1
X-Api-Version2
AuthorizationBearer YOUR-API-KEY
Acceptapplication/json
Example response
HTTP/1.1 200 OK
Content-Typeapplication/json; charset=utf-8
Cache-Controlcache-control: max-age=0, private, must-revalidate
X-RateLimit-Limit30
X-RateLimit-Remaining28
{ "data": { "type": "item", "id": "4235", "attributes": { "title": "My first blog post!", "content": "Lorem ipsum dolor sit amet...", "category": "24", "image": "1235" }, "relationships": { "item_type": { "data": { "type": "item_type", "id": "44" } }, "creator": { "data": { "type": "account", "id": "312" } } }, "meta": { "created_at": "", "updated_at": "", "published_at": null, "first_published_at": null, "publication_scheduled_at": null, "status": null, "is_valid": true } }, "included": [ { "type": "item_type", "id": "44", "attributes": { "name": "Blog post", "api_key": "post", "collection_appeareance": "compact", "singleton": false, "all_locales_required": false, "sortable": true, "modular_block": false, "draft_mode_active": false, "tree": false, "ordering_direction": null, "has_singleton_item": true }, "relationships": { "menu_item": { "data": null }, "singleton_item": { "data": null }, "fields": { "data": [ { "type": "field", "id": "124" } ] }, "title_field": { "data": null }, "ordering_field": { "data": null } } } ] }