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.

AttributeTypeDescription
idStringUnique identifier for the object.
nameStringHuman-readable name of the asset.
descriptionStringDescription of the asset, often maps to alt-text.
pathStringFile path of the asset.
urlStringImage 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.
extensionStringFile extension of the asset on disk e.g. jpg or pdf.
mime_typeStringMime type of the stored file e.g. image/jpeg or application/pdf.
is_imageBooleanHelper attribute which is true if the file is an image.
widthInteger or nullWidth of the image if applicable.
heightInteger or nullHeight 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.

AttributeTypeDescription
idStringUnique identifier for the object.
nameStringThe full name of the user.
emailStringThe email of the user.
profile_photo_urlString or nullThe 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

AttributeTypeDescription
idStringUnique identifier for the object.
published_atStringDatetime string of the date the content was published in ISO8601 format.
slugString or nullKebab 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.
uriString or nullThe computed URI for this content object, if applicable. It will take into account the URI setting on the content type used by this content object.
urlString or nullThe full URL of the object, which is a combination of the URL stored in your Site Settings and the URI of this object.
nameStringCached name of the content object, this will usually be the result of whatever field has had its is_name property set to true.
authorObjectAn author object.
content_typeObjectA content type object.
seoObjectA SEO object.
fieldsObjectA 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"
  },
  "seo": {
    "title": "The Growth of Vertical SaaS",
    "description": "In recent years SaaS has gone mainstream and we are now witnessing the emergence of Vertical SaaS, which this article will explore in more detail.",
    "robots": null,
    "canonical_url": "http://www.contento.io/blog/vertical-saas",
    "open_graph": {
      "title": "The Growth of Vertical SaaS",
      "description": "In recent years SaaS has gone mainstream and we are now witnessing the emergence of Vertical SaaS, which this article will explore in more detail.",
      "image_secure_url": "https://assets.contento.io/assets/s_01H0j30ceEKk3Ge7hq9bBgY065/The-Growth-of-Vertical-SaaS-blog.jpg",
      "image_width": null,
      "image_height": null,
      "image_alt": null,
      "url": "http://www.contento.io/blog/vertical-saas"
    }
  },
  "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.

AttributeTypeDescription
idStringUnique identifier for the object.
nameStringHuman-readable name of the content type, updatable by team admins.
handleStringUnique human-readable identifier, set by team admins at object creation.
object_typeStringThe 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"
}

SEO

AttributeTypeDescription
titleStringMeta Title for the page.
descriptionStringMeta Description for the page.
robotsString or nullThe robots setting for the page.
canonical_urlStringThe canonical Url setting for the page.
open_graphObjectAn Open Graph object.

Example:

{
  "title": "The Growth of Vertical SaaS",
  "description": "In recent years SaaS has gone mainstream and we are now witnessing the emergence of Vertical SaaS, which this article will explore in more detail.",
  "robots": null,
  "canonical_url": "http://www.contento.io/blog/vertical-saas",
  "open_graph": {...}
}

Open Graph

AttributeTypeDescription
titleStringOpen Graph Meta Title for the page.
descriptionStringOpen Graph Meta Description for the page.
image_secure_urlString or nullOpen Graph image url for the page.
image_widthString or nullOpen Graph image width if required.
image_heightString or nullOpen Graph image height if required.
image_altString or nullOpen Graph image alt.
urlStringOpen Graph url.

Example:

{
  "title": "The Growth of Vertical SaaS",
  "description": "In recent years SaaS has gone mainstream and we are now witnessing the emergence of Vertical SaaS, which this article will explore in more detail.",
  "image_secure_url": "https://assets.contento.io/assets/s_01H0j30ceEKk3Ge7hq9bBgY065/The-Growth-of-Vertical-SaaS-blog.jpg",
  "image_width": null,
  "image_height": null,
  "image_alt": null,
  "url": "http://www.contento.io/blog/vertical-saas"
}

Fields

AttributeTypeDescription
idStringUnique identifier for the object.
nameStringHuman-readable of the field.
handleStringUnique human-readable identifier, set by team admins at object creation.
help_textString or nullSet by admins to help users know what this field is used for.
typeStringWhat 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

AttributeTypeDescription
assetsArrayAn array of objects containing the following attributes.
assets.sortIntegerSort value of the individual asset.
assets.assetObjectAn asset object.

Example:

{
  ...,
  "assets": [
    {
      "sort": 0,
      "asset": {
        ...
      }
    },
    {
      "sort": 1,
      "asset": {
        ...
      }
    }
  ]
}

Blocks

AttributeTypeDescription
blocksArrayAn array of objects containing the following attributes.
blocks.nameStringCached name of the block object, this will usually be the result of whatever field has had its is_name property set to true.
blocks.sortIntegerSort value of the individual block.
blocks.fieldsObjectA map of field handles and field objects.
blocks.content_typeObjectThe 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"
      }
    },
    ...
  ]
}
AttributeTypeDescription
content_linksArrayAn array of objects containing the following attributes.
content_links.sortIntegerSort value of the individual link.
content_links.content_linkObject or StringA content object without the author or content_type keys, or a reference string (e.g. ref:c_01H4G0ERMbEnrr83ZCVan3s9T6).

Example:

{
  ...,
  "content_links": [
    {
      "sort": 0,
      "content_link": {
        "id": "c_01H4FYwdW88ayPt0f0F551B51b",
        "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": "c_01H4G0ERMbEnrr83ZCVan3s9T6",
        "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"
          },
          ...
        }
      }
    },
    ...
  ]
}

Circular References

Circular references will occur when you use Content Links to reference pages that then in some way reference themselves.

For example, you might have Page 1 link to Page 2, which links to Page 1 again ... to avoid endless loops we detect and prevent circular references by not continuing to expand content objects in the content_link property.

In this situation you will instead see a reference string, so the content_link property will contain ref:c_01H4G0ERMbEnrr83ZCVan3s9T6 or similar.

Date

AttributeTypeDescription
dateString or nullDatetime string in ISO8601 format.

Example:

{
  ...,
  "date": "2022-08-31T09:16:00+00:00"
}

Decimal

AttributeTypeDescription
numberStringThe stored number to two decimal places as a string.

Example:

{
  ...,
  "number": "3.14"
}
AttributeTypeDescription
selected_optionObjectAn object of the selected option containing the following attributes.
selected_option.labelStringThe option label.
selected_option.valueStringThe option value.

Example:

{
  ...,
  "selected_option": {
    "label": "Rick Astley",
    "value": "rick_astley"
  }
}

Integer

AttributeTypeDescription
numberIntegerThe stored number as an integer.

Example:

{
  ...,
  "number": 42
}

List

AttributeTypeDescription
listArrayAn array of objects containing the following attributes.
list.sortIntegerSort value of the individual item in the list.
list.textString or nullString 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

AttributeTypeDescription
textString or nullHTML 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

AttributeTypeDescription
textString or nullString of text.

Example:

{
  ...,
  "text": "Hello, sunshine."
}

Toggle

AttributeTypeDescription
is_onBooleanEither 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.

AttributeTypeDescription
created_atStringDatetime string in ISO8601 format.
updated_atStringDatetime string in ISO8601 format.

Example:

{
  ...,
  "created_at": "2022-09-15T13:39:40+00:00",
  "updated_at": "2022-09-27T08:59:39+00:00"
}
Previous
Pagination