Working with fields

You can query the extra fields by using the fields as an argument on any content items endpoint.

Start easy with GraphQL

If you are familiar with GraphQL we advise you to take a look at our GraphQL API to easily access content items.

Combining fields

In some cases you want extra data from a content item, for example, created_by, title and items. You can achieve this by combining those fields in one request by separating the fields with a , like created_by,title,items.

The items field contains all content of the item.

Request:

GET: /content_items?fields=created_by,title,items
GET: /content_items/{id}?fields=created_by,title,items

Result:

{
    "id": "00004aaa-6faa-47ae-a595-2911aaecd85d",
    "created_on": "2020-09-16T13:24:22+00:00",
    "changed_on": "2020-10-15T09:45:09+00:00",
    "label": "Publication",
    ...
    "created_by": {
        "id": "8ed9de9b-0000-4215-bc87-f916f72c6cfa",
        "created_on": "2020-09-16T13:24:22+00:00",
        "person": {
            "id": "1d26307b-4e18-0000-9998-3af5215d6bf6",
            "created_on": "2019-09-23T08:53:32+00:00",
            "changed_on": "2020-09-18T09:01:25+00:00",
            "last_seen": "2020-10-15T09:34:10+00:00",
            "blocked_on": null,
            "label": "Person",
            ...
        }
    },
    "title": {
        "en-US": {
            "id": "abf4c67a-9d91-4dcc-ada6-223268f0559e",
            "created_on": "2021-08-25T19:26:27+00:00",
            "changed_on": null,
            "label": "Text",
            "body": "Some title",
            "format": null
        }
    },
    "items": {
      "en-US": {
        ...,
        ...
      },
      "nl-NL": {
        ...
      }
    }
}

Nested fields

Some fields have sub-fields, for example the assigned_to returns a person object. A person object has multiple sub-fields, but for this example we only use the sub-field emails. You can find all sub-fields here.

You can achieve this by nesting those fields in one request with { and } like assigned_to{emails}.

Request:

GET: /content_items?fields=assigned_to{emails}
GET: /content_items/{id}?fields=assigned_to{emails}

Result:

{
    "id": "50290c62-2471-49ab-961f-daaa72d2b832",
    "created_on": "2020-09-16T13:24:22+00:00",
    "changed_on": "2020-10-15T09:56:21+00:00",
    "label": "Publication",
    ...
    "assigned_to": {
        "en-US": {
            "id": "e404d399-0ca6-41dd-b070-6add8570b54e",
            "created_on": "2020-10-15T09:56:21+00:00",
            "person": {
                "id": "df248c8c-3a6d-41bd-ba70-325e200402de",
                "created_on": "2020-10-15T09:56:05+00:00",
                "changed_on": "2020-10-15T09:56:05+00:00",
                "last_seen": "2020-10-15T09:56:05+00:00",
                "blocked_on": null,
                "label": "Person",
                ...
                "emails": {
                    "total": 1,
                    "items": [
                        {
                            "id": "512de3ae-f463-4112-a353-120fadc61fcc",
                            "created_on": "2020-10-15T09:56:05+00:00",
                            "changed_on": null,
                            "label": "Email",
                            "email": "some.random@email.com"
                        }
                    ]
                }
            }
        }
    }
}

Using fields in items

To request the content item main contents you use the field items. To use sub-fields of items. You have to prefix them with the api_id that's set in the PublicationModel. For example, we have a PublicationModel with one field (type Assets) with api_id cover. In this above example, you can access the sub-field cdn_files of your asset field in one request. By combining the following items{cover{cdn_files}}

Request:

GET: /content_items?fields=items{cover{cdn_files}}
GET: /content_items/{id}?fields=items{cover{cdn_files}}

{
    "id": "4cb03949-7e24-4f1e-947a-227b122747d7",
    "created_on": "2020-09-16T13:24:22+00:00",
    "changed_on": "2020-10-15T09:56:21+00:00",
    "label": "Publication",
    ...
    "items": {
        "en-US": {
            ...,
            ...,
        },
        "nl-NL": {
            ...,
            "cover": {
                "items": [
                    {
                        "id": "57b876bd-9619-4356-a63b-69f977cfead9",
                        "created_on": "2020-09-16T14:35:47+00:00",
                        "changed_on": "2020-09-30T15:07:03+00:00",
                        "label": "Photo",
                        ...
                        "cdn_files": {
                            "total": 1,
                            "items": [
                                {
                                    "id": "8c78dada-f346-4972-859a-67b7b0e74a7f",
                                    "created_on": "2020-10-07T10:05:28+00:00",
                                    "changed_on": null,
                                    "label": "CdnFile",
                                    ...
                                    "url": "https://rDQB4vf31z1Ojo7T3De3bU.b-cdn.net/{format}/s3-starfm-dev/6c65d9b7-cf98-41cc-b9af-24ddeb0d4c5e.jpg",
                                    "extension": null
                                }
                            ]
                        }
                    }
                ],
                "label": "Asset"
            },
            ...,
            ...,
        }
    }
}

Most used fields

In the most common cases you use one or multiple of following fields items, title, model, locales, status, environment, created_by, updated_by, assigned_to, channels, containers.

Combined: items,title,model,locales,status,environment,created_by,updated_by,assigned_to,channels,containers