Content API
Object Reference
When working with the Content API you will be given JSON responses that contain various kinds of objects. This page outlines the reference JSON structure for each type of object that exists in the API.
Most of the time you will request a primary object of a specific type such as a Content or Asset object. Sometimes, there will be other types of objects that form part of the primary one.
Assets
Asset objects only ever appear as part of an asset field object. At present, they can’t be fetched on their own.
Attribute | Type | Description |
---|---|---|
id | String | Unique identifier for the object. |
name | String | Human-readable name of the asset. |
description | String | Description of the asset, often maps to alt-text. |
path | String | File path of the asset. |
url | String | Image API URL of the asset. If its not an image then query parameters for image manipulations will have no effect on the file, it will simply be delivered as-is. |
extension | String | File extension of the asset on disk e.g. jpg or pdf . |
mime_type | String | Mime type of the stored file e.g. image/jpeg or application/pdf . |
is_image | Boolean | Helper attribute which is true if the file is an image. |
width | Integer or null | Width of the image if applicable. |
height | Integer or null | Height of the image if applicable. |
Example:
{
"id": "Gzb7AQ7pOZ",
"name": "Grimacing Face Balloon",
"description": "Bright yellow balloon of the grimacing face emoji.",
"path": "assets/Gzb7AQ7pOZ/grimacing-face-balloon.jpg",
"url": "https://assets.contento.io/assets/Gzb7AQ7pOZ/grimacing-face-balloon.jpg",
"extension": "jpg",
"size": "3.6 MB",
"mime_type": "image/jpeg",
"is_image": true,
"width": 6000,
"height": 4000
}
Authors
Author objects are only present as part of a content object. They reference the user account of the person who initially created the object.
Attribute | Type | Description |
---|---|---|
id | String | Unique identifier for the object. |
name | String | The full name of the user. |
email | String | The email of the user. |
profile_photo_url | String or null | The URL of the user’s profile photo. This uses the Image API and can accept manipulation parameters. |
Example:
{
"id": "RaDf2yMpL6",
"name": "Josh Angell",
"email": "[email protected]",
"profile_photo_url": "https://assets.contento.io/profile-photos/caX2ahJ8YNRnNgHHqSWVcZIKjilNfMmeJMdS4sL5.jpg"
}
Content
Attribute | Type | Description |
---|---|---|
id | String | Unique identifier for the object. |
published_at | String | Datetime string of the date the content was published in ISO8601 format. |
slug | String | Kebab case slug for use in URLs. Whilst this defaults to kebab case users can type in whatever they like, spaces and other disallowed characters will simply be replaced with hyphens. |
name | String | Cached name of the content object, this will usually be the result of whatever field has had its is_name property set to true . |
author | Object | An author object. |
content_type | Object | A content type object. |
fields | Object | A map of field handles and field objects. |
Example:
{
"id": "RaDf2yMpL6",
"published_at": "2022-09-27T08:54:06+00:00",
"slug": "vertical-saas",
"name": "The Growth of Vertical SaaS",
"author": {
"id": "RaDf2yMpL6",
"name": "Josh Angell",
"email": "[email protected]",
"profile_photo_url": "https://assets.contento.io/profile-photos/caX2ahJ8YNRnNgHHqSWVcZIKjilNfMmeJMdS4sL5.jpg"
},
"content_type": {
"id": "RaDf2yMpL6",
"name": "Blog Post",
"handle": "blog_post",
"object_type": "page"
},
"fields": {
"title": {
"id": "RaDf2yMpL6",
"name": "Title",
"handle": "title",
"help_text": "Used as the H1 on the post detail page.",
"type": "text",
"text": "The Growth of Vertical SaaS"
},
...
}
}
Content Types
Content type objects can appear on content or block objects. At present, they can’t be fetched on their own.
Attribute | Type | Description |
---|---|---|
id | String | Unique identifier for the object. |
name | String | Human-readable name of the content type, updatable by team admins. |
handle | String | Unique human-readable identifier, set by team admins at object creation. |
object_type | String | The type of content this content type references. One of page , entry or block . |
Example:
{
"id": "RaDf2yMpL6",
"name": "Blog Post",
"handle": "blog_post",
"object_type": "page"
}
Fields
Attribute | Type | Description |
---|---|---|
id | String | Unique identifier for the object. |
name | String | Human-readable of the field. |
handle | String | Unique human-readable identifier, set by team admins at object creation. |
help_text | String or null | Set by admins to help users know what this field is used for. |
type | String | What kind of field this object represents. One of assets , blocks , content_links , date , decimal , integer , list , long_text , text or toggle . |
Example:
{
"id": "RaDf2yMpL6",
"name": "Title",
"handle": "title",
"help_text": "Used as the H1 on the post detail page.",
"type": "text",
...
}
There are many field types that all extend the base field object above. Outlined below are the additional attributes and values each type of field can add to the base field.
Assets
Attribute | Type | Description |
---|---|---|
assets | Array | An array of objects containing the following attributes. |
assets.sort | Integer | Sort value of the individual asset. |
assets.asset | Object | An asset object. |
Example:
{
...,
"assets": [
{
"sort": 0,
"asset": {
...
}
},
{
"sort": 1,
"asset": {
...
}
}
]
}
Blocks
Attribute | Type | Description |
---|---|---|
blocks | Array | An array of objects containing the following attributes. |
blocks.name | String | Cached name of the block object, this will usually be the result of whatever field has had its is_name property set to true . |
blocks.sort | Integer | Sort value of the individual block. |
blocks.fields | Object | A map of field handles and field objects. |
blocks.content_type | Object | The content type object for the individual block. |
Example:
{
...,
"blocks": [
{
"name": "Sign up to our newsletter",
"sort": 0,
"fields": {
"heading": {
"id": "RaDf2yMpL6",
"name": "Heading",
"handle": "heading",
"help_text": null,
"type": "text",
"text": "Sign up to our newsletter"
},
...
},
"content_type": {
"id": "RaDf2yMpL6",
"name": "CTA",
"handle": "cta",
"object_type": "block"
}
},
{
"name": "Single Image",
"sort": 1,
"fields": {
"image": {
"id": "w5D7qq47JP",
"name": "Image",
"handle": "image",
"help_text": null,
"type": "assets",
"assets": [
{
"id": "Gzb7AQ7pOZ",
"name": "Raimond Klavins 0Gg W5Og Pb Q Unsplash",
"description": null,
"path": "assets/Gzb7AQ7pOZ/raimond-klavins-0ggW5og_pbQ-unsplash.jpg",
"url": "https://assets.contento.io/assets/Gzb7AQ7pOZ/raimond-klavins-0ggW5og_pbQ-unsplash.jpg",
"extension": "jpg",
"size": "2.31 MB",
"mime_type": "image/jpeg",
"is_image": true,
"width": 5760,
"height": 3840
},
...
]
},
...
},
"content_type": {
"id": "YPV7lKdvwx",
"name": "Single Image",
"handle": "single_image",
"object_type": "block"
}
},
...
]
}
Content Links
Attribute | Type | Description |
---|---|---|
content_links | Array | An array of objects containing the following attributes. |
content_links.sort | Integer | Sort value of the individual link. |
content_links.content_link | Object | A content object without the author or content_type keys. |
Example:
{
...,
"content_links": [
{
"sort": 0,
"content_link": {
"id": "K6vB6zVv2x",
"published_at": "2022-08-16T18:49:33.000000Z",
"slug": null,
"name": "Cow",
"fields": {
"title": {
"id": "D4GjP89jZe",
"name": "Title",
"handle": "title",
"help_text": null,
"type": "text",
"text": "Cow"
},
...
}
}
},
{
"sort": 1,
"content_link": {
"id": "BM7pRXY08L",
"published_at": "2022-08-16T18:49:27.000000Z",
"slug": null,
"name": "Dog",
"fields": {
"title": {
"id": "D4GjP89jZe",
"name": "Title",
"handle": "title",
"help_text": null,
"type": "text",
"text": "Dog"
},
...
}
}
},
...
]
}
Date
Attribute | Type | Description |
---|---|---|
date | String or null | Datetime string in ISO8601 format. |
Example:
{
...,
"date": "2022-08-31T09:16:00+00:00"
}
Decimal
Attribute | Type | Description |
---|---|---|
number | String | The stored number to two decimal places as a string. |
Example:
{
...,
"number": "3.14"
}
Dropdown
Attribute | Type | Description |
---|---|---|
selected_option | Object | An object of the selected option containing the following attributes. |
selected_option.label | String | The option label. |
selected_option.value | String | The option value. |
Example:
{
...,
"selected_option": {
"label": "Rick Astley",
"value": "rick_astley"
}
}
Integer
Attribute | Type | Description |
---|---|---|
number | Integer | The stored number as an integer. |
Example:
{
...,
"number": 42
}
List
Attribute | Type | Description |
---|---|---|
list | Array | An array of objects containing the following attributes. |
list.sort | Integer | Sort value of the individual item in the list. |
list.text | String or null | String of the entered text. |
Example:
{
...,
"list": [
{
"text": "Never gonna give you up",
"sort": 1
},
{
"text": "Never gonna let you down",
"sort": 2
},
{
"text": "Never gonna run around and desert you",
"sort": 3
},
{
"text": "Never gonna make you cry",
"sort": 4
},
{
"text": "Never gonna say goodbye",
"sort": 5
},
{
"text": "Never gonna tell a lie and hurt you",
"sort": 6
},
...
]
}
Long Text
Attribute | Type | Description |
---|---|---|
text | String or null | HTML encoded string of the raw output from the rich text editor. |
Example:
{
...,
"text": "<p>Glaoch na h\u00c9ireann<br>Chugainn an l\u00e1 is chugainn an d\u00fashl\u00e1n,<br>R\u00e9 na cumhachta is na gl\u00f3ire,<br>\u2018S\u00e9 glaoch na t\u00edre a fhreagr\u00f3im\u00eds,<br>\u00d3 cheithre ch\u00faige na h\u00c9ireann.<\/p>\n\n<p><strong>Curf\u00e1:<\/strong><br>\u00c9ire,\u00c9ire,<br>Is treise sinn mar shlua,<br>Gualainn le gualainn,<br>\u00c9ireoidh linn gan dua.<\/p>"
}
Text
Attribute | Type | Description |
---|---|---|
text | String or null | String of text. |
Example:
{
...,
"text": "Hello, sunshine."
}
Toggle
Attribute | Type | Description |
---|---|---|
is_on | Boolean | Either true or false . |
Example:
{
...,
"is_on": true
}
Timestamps
There are two timestamp attributes that can appear on the top level object that you are requesting. For example if you make a request to the /content/{id}
endpoint then you’ll get back a single content object. This will contain the timestamps on it as well as the base object, but all other objects that hang off the top level one will not have timestamps on them.
The timestamps refer to the dates the root object was created on or last updated at.
Attribute | Type | Description |
---|---|---|
created_at | String | Datetime string in ISO8601 format. |
updated_at | String | Datetime string in ISO8601 format. |
Example:
{
...,
"created_at": "2022-09-15T13:39:40+00:00",
"updated_at": "2022-09-27T08:59:39+00:00"
}