Object Reference - Contento

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/flfrsFQUNUknRmrPhwlobzWV4o3TBmydGXUn89RK.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` or `null`	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`.
`uri`	`String` or `null`	The 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.
`url`	`String` or `null`	The full URL of the object, which is a combination of the URL stored in your Site Settings and the URI of this object.
`language`	`String`	The language identifier this content is in, by default this will be set to whatever the default language is for your site e.g. `en`.
`author`	`Object`	An author object.
`content_type`	`Object`	A content type object.
`seo`	`Object`	A SEO 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",
  "uri": "blog/vertical-saas",
  "url": "https://www.contento.io/blog/vertical-saas",
  "language": "en",
  "author": {
    "id": "RaDf2yMpL6",
    "name": "Josh Angell",
    "email": "[email protected]",
    "profile_photo_url": "https://assets.contento.io/profile-photos/flfrsFQUNUknRmrPhwlobzWV4o3TBmydGXUn89RK.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.

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"
}

SEO

Attribute	Type	Description
`title`	`String`	Meta Title for the `page`.
`description`	`String`	Meta Description for the `page`.
`robots`	`String` or `null`	The robots setting for the `page`.
`canonical_url`	`String`	The canonical Url setting for the `page`.
`open_graph`	`Object`	An 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

Attribute	Type	Description
`title`	`String`	Open Graph Meta Title for the `page`.
`description`	`String`	Open Graph Meta Description for the `page`.
`image_secure_url`	`String` or `null`	Open Graph image url for the `page`.
`image_width`	`String` or `null`	Open Graph image width if required.
`image_height`	`String` or `null`	Open Graph image height if required.
`image_alt`	`String` or `null`	Open Graph image alt.
`url`	`String`	Open 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

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` or `String`	A 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

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"
}

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"
}

Assets

Authors

Content

Content Types

SEO

Open Graph

Fields

Assets

Blocks

Content Links

Date

Decimal

Dropdown

Integer

List

Long Text

Text

Toggle

Timestamps