Working with fields
Use the fields argument in any REST API content items endpoint to choose the content fields that you want to see in the response.
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.
Combine fields
You can combine different fields in the fields argument of the request to choose all the content that you want to see in the response such as items, title, model, locales, workflow_stage, environment, created_by, updated_by, and assigned_to. See the example request and response below when combining some fields.
GET: /content_items?fields=created_by,title,items
GET: /content_items/{id}?fields=created_by,title,items
{
"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 want to see the sub-field emails. You can find all sub-fields here.
You can achieve this by nesting those fields in the argument of the request with { and } like in the example below.
GET: /content_items?fields=assigned_to{emails}
GET: /content_items/{id}?fields=assigned_to{emails}
{
"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"
}
]
}
}
}
}
}
Content fields
To request the main content include the field items in the fields argument. To see sub-fields of items, specify the api_id of the sub-field in the argument. Go to Schema > Model > Field type settings to get the api_id of the fields that you want to include. For example, a content item has a cover image field (type Assets) with api_id cover.
In this example, you can access the sub-field cdn_files of your asset field in one request like in the example below.
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"
},
...,
...,
}
}
}
Field types
The list of field types returned in the items array of a content item depends on the related model. In the example responses below, you can see that the api_id of each field is returned in items.
Here is a list of field types to give you a better understanding of what to expect in the response of a GET request.
Text
The Text field can be a single line, multiple lines, or HTML like in the example response below.
{
"items": {
"en-US": { // The content item entry for this locale.
"title": {
// API Id of a single line text field
"id": "gmQh3QLgu80l1QLMg9qUj6nwr97YxqkbPhhUf7rO",
"created_on": "2023-01-01T09:56:21+00:00",
"changed_on": null,
"label": "Text",
"body": "Headline",
"format": null
},
"my_text_area": {
// API Id of a text area field with multiple lines
"id": "gmQh3QLgu80l1QLMg9qUj6nwr97YxqkbPhhUf7rO",
"created_on": "2023-01-01T09:56:21+00:00",
"changed_on": null,
"label": "Text",
"body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi u",
"format": null
},
"my_html_text": {
// API Id of an HTML text field
"id": "gmQh3QLgu80l1QLMg9qUj6nwr97YxqkbPhhUf7rO",
"created_on": "2023-01-01T09:56:21+00:00",
"changed_on": null,
"label": "Text",
"body": "<h1>Heading 1 </h1><h2>Heading 2 </h2><p><strong>Some bold text <em>and italic</em></strong></p><ul><li>First bullet</li><li>Second bullet</li></ul><ol><li>Step 1</li></ol><p><a href=\"http://docs.prepr.io/\" rel=\"noopener noreferrer\" target=\"_blank\">A useful link</a></p><p><br></p><p style=\"text-align: right;\"><a href=\"https://mandylingham6.files.prepr.io/72bk28xzmk8e-step5.svg\"></a>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>",
"format": null
}
}
}
}
Dynamic content
The Dynamic content field contains embedded videos, social media posts, maps, assets, and components for rich content items like in the example request below.
{
"items": {
"en-US": { // The content item entry for this locale.
"content": { // The API Id of the dynamic content field
"items": [
{ // Embedded heading text in the dynamic content field
"id": "aa82833a-7b0c-413c-b8e5-e463efb32903",
"created_on": "2023-09-27T15:05:25+00:00",
"changed_on": null,
"label": "Text",
"body": "Ingredients",
"format": "H2"
},
{ // Embedded bullet points in the dynamic content field
"id": "d0ea8c21-0826-46ee-b559-3fb838daa1c7",
"created_on": "2023-09-27T15:05:25+00:00",
"changed_on": null,
"label": "Text",
"body": "<ul><li>first bullet point</li><li>second bullet point</li></ul>",
"format": null
},
{ // Embedded ordered list in the dynamic content field
"id": "f7e27135-f5b8-46e8-b103-f1f7807f7a6e",
"created_on": "2023-09-27T15:05:25+00:00",
"changed_on": null,
"label": "Text",
"body": "<ol><li>step 1</li><li>step 2</li></ol>",
"format": null
},
{ // Embedded table in the dynamic content field
"id": "6c8bc9fa-256c-499c-8636-3452cb02176a",
"created_on": "2023-09-27T15:05:25+00:00",
"changed_on": null,
"label": "Text",
"body": "<table style=\"width: 100%;\"><tbody><tr><td style=\"width: 50.0000%;\"><strong>Pros</strong></td><td><strong>Cons</strong></td></tr><tr><td style=\"width: 50.0000%;\">Tasty</td><td style=\"width: 50.0000%;\">Lots of calories</td></tr><tr><td style=\"width: 50.0000%;\">Easy to make</td><td style=\"width: 50.0000%;\">Need to use the oven</td></tr></tbody></table>",
"format": null
},
{ // An embedded asset field
"label": "Asset",
"items": [
{
"id": "6059ecee-270f-46b0-b286-2e3e9374d33a",
"created_on": "2023-09-20T11:55:11+00:00",
"changed_on": "2023-09-20T13:12:27+00:00",
"label": "Photo",
"name": "blueprint",
"body": null,
"author": null,
"status": null,
"replaceable": true,
"reference_id": null,
"width": 1141,
"height": 1280,
"extension": "jpg",
"original_name": "blueprint",
"mime_type": "image/jpeg"
}
]
},
{ // An embedded location field
"id": "6059ecee-270f-46b0-b286-2e3e9374d33a",
"created_on": "2023-09-20T11:55:11+00:00",
"changed_on": "2023-09-20T13:12:27+00:00",
"label": "Coordinates",
"latitude": "52.3736018",
"longitude": "4.9002881"
}
],
"label": "ElementBox"
}
}
}
}
Assets
Assets are images, videos, and audio files or documents that are linked to a content item.
{
"items": {
"en-US": { // The content item entry for this locale.
"cover": { // API Id of the Asset field
"items": [
{
"id": "bac0aa60-dfa3-4f4e-9261-35a4fc693a76",
"created_on": "2022-11-23T12:50:33+00:00",
"changed_on": "2022-11-23T12:50:33+00:00",
"label": "Photo",
"name": "bg-cta-1",
"body": null,
"author": null,
"status": null,
"replaceable": true,
"reference_id": null,
"width": 1919,
"height": 939,
"extension": "png",
"original_name": "bg-cta-1",
"mime_type": "image/png"
}
],
"label": "Asset"
}
}
}
}
Integer
Integers are whole numbers, and are often used to store stock quantities, prices in cents, etc. like in the example below.
{
"items": {
"en-US": { // The content item entry for this locale.
"quantity": { // API Id of the Integer field
"id": "e356b423-71bc-40b5-8b6b-0611108658be",
"created_on": "2023-03-14T16:34:16+00:00",
"changed_on": null,
"label": "Integer",
"value": 122
}
}
}
}
Float
Float types are number entries with decimal places, for accurate calculation such as the price of an item, distance, or weight.
{
"items": {
"en-US": { // The content item entry for this locale.
"price": { // API Id of the Float field
"id": "69f6f04b-719e-49fd-b80c-b0037f495a31",
"created_on": "2023-03-14T16:34:16+00:00",
"changed_on": null,
"label": "Float",
"value": 122.12
}
}
}
}
Boolean
The Boolean field has one of two possible values: true or false.
{
"items": {
"en-US": { // The content item entry for this locale.
"needs_social_post": { // API Id of the Float field
"id": "4d32c2f1-69cd-4280-abe1-f5e548584417",
"created_on": "2023-03-09T09:45:23+00:00",
"changed_on": null,
"label": "Boolean",
"value": true
}
}
}
}
Stack
The Stack field contains a list of (personalized) models/components. This is a powerful type that allows you to create a site using the Stack field as your page builder.
{
"items": {
"en-US": { // The content item entry for this locale.
"stack": { // The API Id of a stack field
"items": [ // Contains all components and items in the stack
{ // A link to an existing Call to action content item
"id": "4c0622c1-f635-4a0a-83de-8f56bc5b9ea4",
"created_on": "2023-03-17T10:07:30+00:00",
"changed_on": "2023-03-17T10:07:30+00:00",
"label": "Publication",
"read_time": {
"en-GB": 1
},
"publish_on": {
"en-GB": "2023-03-17T10:07:00+00:00"
}
},
{ // Embedded component
"items": {
"description": {
"id": "006e3c8e-ea6b-44bd-886d-abcdf5357b6a",
"created_on": "2023-03-17T10:11:43+00:00",
"changed_on": null,
"label": "Text",
"body": "As far back as I can remember, I've always eaten french toast. It was usually a quick Sunday morning breakfast instead of pancakes or the go-to snack to use up the last stale bread slices. This is one of the easiest recipes that you can find for a quick treat.",
"format": null
},
"social_media_image": {
"items": [
{
"id": "54bbbdda-470b-4048-9a9e-0b3bca205003",
"created_on": "2023-03-09T14:16:39+00:00",
"changed_on": "2023-03-09T14:16:47+00:00",
"label": "Photo",
"name": "French toast",
"body": null,
"author": null,
"status": null,
"replaceable": true,
"reference_id": null,
"width": 3024,
"height": 4032,
"extension": "jpg",
"original_name": "4tq8iogbqhfi-pexels-sean-stevens-4623075",
"mime_type": "image/jpeg"
}
],
"label": "Asset"
},
"title": {
"id": "9a087714-324c-41cb-96c6-212f410cdf74",
"created_on": "2023-03-17T10:11:43+00:00",
"changed_on": null,
"label": "Text",
"body": "Excuse my french toast",
"format": null
}
},
"id": "1f3dec32-96e1-410a-bda8-22a634f9fd26",
"label": "PublicationElement"
// Label for component
}
]
}
}
}
}
Content Reference
The Content reference field contains a link between one or more models like in the example below.
{
"items": {
// The content item entry for this locale.
"en-US": {
// API Id of a content reference field
"authors": {
"items": [
{
// Id of the existing content item
"id": "a69bebd0-b438-41ab-8fc8-86353afaf57e",
"created_on": "2023-01-27T10:35:52+00:00",
"changed_on": "2023-01-30T08:43:51+00:00",
"label": "Publication",
"read_time": {
"en-GB": 1
},
"publish_on": {
"en-GB": "2023-01-27T10:35:00+00:00"
}
}
],
// Label for a content reference
"label": "Publication"
}
}
}
}
Component
Components are often used to represent a set of reusable fields. Also, it can be added as a custom element to the Dynamic content or Stack fields.
{
"items": {
// The content item entry for this locale.
"en-US": {
// The API Id of the embedded component
"seo": {
"items": {
// API Id of a text field in the component
"description": {
"id": "6eefa140-c2f4-499e-a236-794936eeb057",
"created_on": "2023-09-25T09:31:37+00:00",
"changed_on": null,
"label": "Text",
"body": "test",
"format": null
},
// API Id of the asset field in the component
"social_media_image": {
"items": [
{
"id": "6059ecee-270f-46b0-b286-2e3e9374d33a",
"created_on": "2023-09-20T11:55:11+00:00",
"changed_on": "2023-09-20T13:12:27+00:00",
"label": "Photo",
"name": "blueprint",
"body": null,
"author": null,
"status": null,
"replaceable": true,
"reference_id": null,
"width": 1141,
"height": 1280,
"extension": "jpg",
"original_name": "blueprint",
"mime_type": "image/jpeg"
}
],
"label": "Asset"
},
// API Id of a text field in the component
"title": {
"id": "baffc883-5104-4cc9-8813-c8920a943867",
"created_on": "2023-09-25T09:31:37+00:00",
"changed_on": null,
"label": "Text",
"body": "Test SEO title",
"format": null
}
},
// Component Id and label of the embedded component
"id": "85461317-fd8e-40f8-b453-dbf6ef9c68dd",
"label": "PublicationElement"
}
}
}
}
Remote content
The Remote content field references content in an external CMS, legacy system of eCommerce platform. Check out the Content Integration setup guide for more details.
{
"items": {
// The content item entry for this locale.
"en-US": {
// The API Id of the remote content field
"products": {
"items": [
{
"id": "1",
"body": "Pizza slicer",
"description": "This handy tool has more uses than you may realize. It can be used to slice your pizza and shape dough for the perfect pies.",
"image_url": "https://prepr-example-show-content-demo-patterns.stream.prepr.io/w_1920,h_1080/4frprlq6w4k6-pizza-slicer.png",
"data": {
"sku_id": 1,
"price": 1299,
"stock": 5
},
"content_integration": {
"id": "62cc3bec-6978-4ba6-a699-d379ff0a93de"
}
}
],
"label": "ContentIntegrationItem"
}
}
}
}
Note
Key Value data can be passed from the connected API to Prepr. If a new version of an item is available in the Content Integration response Prepr is able to automatically update the version of the item in the content item response.
Date & Time
The Date and time field adheres to the ISO 8601 standard. This field content differs in the response depending on the following field settings:
- The Type - This type can be either Date, Date range or Business hours which you can identify from the
labellike in the example below. - Time selection - When time selection is enabled the format is
Y-m-d H:i:sinstead ofY-m-d. - Multiple dates - When Allow extra dates is enabled, the field will be an
itemsarray like in the example below.
{
"items": {
"en-US": { // The content item entry for this locale.
"event_date": {
// The API Id of a date field without time
"id": "73fd5c62-78b4-434a-966b-4aba04f3648a",
"created_on": "2023-01-01T16:25:53+00:00",
"changed_on": null,
"label": "DateTime",
"value": "2023-01-01",
"format": "Y-m-d"
},
"start_date_and_time": {
// The API Id of a date field with time
"id": "c1c5c7cf-d737-4fd9-9949-940b84cbf454",
"created_on": "2023-01-01T16:28:21+00:00",
"changed_on": null,
"label": "DateTime",
"value": "2023-01-01 18:25:00",
"format": "Y-m-d H:i:s"
},
"project_duration": {
// The API Id of a date field with ranges
"id": "abb46555-013f-4e2e-871e-344b243332f6",
"created_on": "2023-01-01T16:25:53+00:00",
"changed_on": null,
"label": "DateTimeRange",
"from": "2023-01-01",
"until": "2024-12-31",
"format": "Y-m-d"
},
"event_duration": {
// The API Id of a date field with ranges including time
"id": "efd799d9-ee9d-4ec1-8cc3-487b1ecb347a",
"created_on": "2023-01-01T16:25:53+00:00",
"changed_on": null,
"label": "DateTimeRange",
"from": "2023-01-01 00:00:00",
"until": "2024-12-31 23:59:59",
"format": "Y-m-d H:i:s"
},
"seasons": {
// The API Id of a date field with multiple date ranges
"items": [
{
"id": "2d701a86-7867-479a-bf09-36dbd847a36f",
"created_on": "2023-01-01T16:28:21+00:00",
"changed_on": null,
"label": "DateTimeRange",
"from": "2023-12-01",
"until": "2024-02-29",
"format": "Y-m-d"
},
{
"id": "72df271a-ebda-4372-b1ab-9d5ca36ef585",
"created_on": "2023-06-01T16:28:21+00:00",
"changed_on": null,
"label": "DateTimeRange",
"from": "2023-09-01",
"until": "2023-11-30",
"format": "Y-m-d"
},
...
],
"label": "DateTimeRange"
},
"opening_times" : {
// The API Id of a date field with Business hours type
"items": [
{
"id": "50425271-b86c-4d0a-886e-988642808d77",
"created_on": "2023-03-13T10:59:21+00:00",
"changed_on": null,
"label": "BusinessHours",
"state": "open",
"open_day": 1,
//Days are defined as 1 through 7, starting on Monday. So Monday would be 1, Tuesday would be 2, and so on.
"open_time": "00:00",
"close_day": 2,
"close_time": "00:00",
"valid_from": null,
"valid_until": null
},
{
"id": "c9509f72-e277-49e1-bbc5-2a31df543cae",
"created_on": "2023-03-13T10:59:21+00:00",
"changed_on": null,
"label": "BusinessHours",
"state": "open",
"open_day": 2,
"open_time": "04:30",
"close_day": 3,
"close_time": "01:30",
"valid_from": null,
"valid_until": null
},
{
"id": "9b602eb5-e376-4965-9837-d604350d0724",
"created_on": "2023-03-13T10:59:21+00:00",
"changed_on": null,
"label": "BusinessHours",
"state": "open",
"open_day": 2,
"open_time": "01:30",
"close_day": 2,
"close_time": "02:00",
"valid_from": null,
"valid_until": null
}
],
"label": "BusinessHours"
}
}
}
}
Location
The Location field contains Google Maps coordinates of a specific location in the content item.
{
"items": {
"en-US": { // The content item entry for this locale.
"office_location": { // API Id of the location field
"id": "18e6f038-7766-4c65-8ef0-89e1c6a32926",
"created_on": "2023-01-01T16:05:08+00:00",
"changed_on": null,
"label": "Coordinates",
"latitude": 21.3137,
"longitude": -157.806
}
}
}
}
Resource
The Resource field contains a link to an internal or external webpage and is only available within a component.
{
"items": {
"en-US": {
"events_collection": {
// The Api Id of the component field in the content item
"items": {
"description": { // The Api Id of a text field in the component
"id": "baffc883-5104-4cc9-8813-c8920a943867",
"created_on": "2023-09-25T09:31:37+00:00",
"changed_on": null,
"label": "Text",
"body": "Join the latest events.",
"format": null
},
"events_page": { // The Api Id of the resource field in this component
"id": "87d97825-5072-4ee0-a0c3-d19a7070ee0a",
"created_on": "2023-03-14T16:54:50+00:00",
"changed_on": null,
"label": "Resource",
"body": "Fall Bake-a-thon",
"url": "https://patterns.prepr.io/livestream/live/fall-bake-a-thon",
"type": "Webpage"
}
},
"id": "85461317-fd8e-40f8-b453-dbf6ef9c68dd",
"label": "PublicationElement"
// Label for the component
}
}
}
}
Social
The Social field contains embedded social posts in the content item. The label depends on the social platform and will be one of these values: TwitterPost, InstagramPost, YouTubePost, FacebookPost, VimeoPost, SoundCloudPost, SpotifyPlaylist, TikTokPost, ApplePodcast.
{
"items": {
"en-US": {
"weekly_social_post": {
// The Api Id of a social field in the content item
"id": "fe556b3f-20a1-416d-a6c7-baa7ccf29ead",
"created_on": "2023-01-01T10:04:57+00:00",
"changed_on": null,
"label": "TwitterPost",
"url": "https://twitter.com/SpaceX/status/1633941127081652224?s=20"
}
}
}
}
Color
The Color field includes a HEX code.
{
"items": {
"en-US": {
"border_color": {
// The Api Id of a color field in the content item
"id": "3035280e-c171-42cd-a643-c1fee2083543",
"created_on": "2023-03-13T11:49:58+00:00",
"changed_on": null,
"label": "Color",
"body": "#c73434",
"format": "Color"
}
}
}
}
Tag
The Tag field includes tags like keywords for your content item.
// The Tag field returns an array of tag items:
{
"items": {
"en-US": {
"search_keywords": { // The API Id of a Tags field in the content item
"items": [ // An items array with a list of tags
{
"id": "7ca6249b-7b63-4f96-a090-c92b5c297a11",
"created_on": "2023-03-09T09:45:23+00:00",
"changed_on": null,
"label": "Tag",
"body": "awesome",
"slug": "awesome"
},
{
"id": "7ca6249b-7b63-4f96-a090-c92b5c297a11",
"created_on": "2023-03-09T09:45:23+00:00",
"changed_on": null,
"label": "Tag",
"body": "great",
"slug": "great"
},
{
"id": "7ca6249b-7b63-4f96-a090-c92b5c297a11",
"created_on": "2023-03-09T09:45:23+00:00",
"changed_on": null,
"label": "Tag",
"body": "awesome and great",
"slug": "awesome and great"
},
],
"label": "Tag"
}
}
}
}