Preview API

Each space has a name, a set of locales, and metadata about the space.

In the JSON response of a successful query, linked items are placed in the includes array, when not already fetched in the items array.

Note: Links in the Delivery API will always only resolve to published entries. Unresolved items will not be present in the includes array. The Preview API will include draft entries with the same caveat that unresolved links will not appear in the includes array.

The include array is not applicable while retrieving a single entry.

When querying an entry collection that contains at least one unresolvable reference (for example, an entry that was referenced by another entry has been deleted, or the referenced entry is Archived or in Draft), an errors array is returned in the response. This also occurs when there are permission issues.

An example of the errors array in the response:

{
  "errors": [
    {
      "sys": {
        "id": "notResolvable",
        "type": "error"
      },
      "details": {
        "type": "Link",
        "linkType": "Entry",
        "id": "2bhYOW3HpzPgLPCDdwRrUB"
      }
    },
    {
      "sys": {
        "id": "notResolvable",
        "type": "error"
      },
      "details": {
        "type": "Link",
        "linkType": "Entry",
        "id": "Q1GLCTVUJgxsz9gYXFnl4"
      }
    }
  ]
}

Note:

• Content types payload comes with a metadata property. This metadata property has as its value a taxonomy list. The taxonomy list contains links to all the concepts and concept schemes assigned to that content type.

• At the moment, it is not possible to get additional information about concepts or concept schemes via the CDA.

Note:

• Entry payloads come with a metadata property. This metadata property has as its value a concepts list. The concept list contains links to all the concepts that exist on the entry or asset.

• At the moment, it is not possible to get additional information about the concepts via the CDA.

• You can query for entries by their concepts. The search is across content types.

The query parameter starts with metadata.concepts.sys.id with operator [all].

The query parameter starts with metadata.concepts.sys.id with operator [in].

The query parameter starts with metadata.concepts.descendants with operator [in].

Note:

• Entries and assets payload come with a metadata property. This metadata property has as its value a tags list. The tags list contains links to all the tags that exist on the entry or asset.

• You can query for entries and assets by their tags. For entries, the search is across content types.

The query parameter starts with metadata.tags.sys.id with operator [all].

The query parameter starts with metadata.tags.sys.id with operator [in].

The query parameter starts with metadata.tags with operator [exists].

When you have related content (e.g. entries with links to image assets) it's possible to include both search results and related data in a single request. Using the include parameter, you can specify the number of levels to resolve.

The maximum number of levels is 10. The API will throw a BadRequestError for higher values or values other than an integer. The default number, if the parameter is not specified, is 1. To omit linked items, specify include as 0.

If the standard items array has not already retrieved the linked entries, they will be in the includes.Entry array. Linked assets are inside the includes.Asset array.

Note: The include parameter resolves links between entries and assets within a space. Links between content types within a space are not included in the response.

Note: The include parameter is only available for the entry collection endpoint /spaces/{space_id}/environments/{environment_id}/entries.

If you want to retrieve all items linked to a specific entry, the query URL should filter entries on their specific content_type, linking_field (field to link items) and entry_id from the target entry.

Notes:

• The include parameter resolves links between entries and assets within a space. Links between content types within a space are not included in the response.

• The include parameter is only available for the entry collection endpoint /spaces/{space_id}/environments/{environment_id}/entries.

To search for entries with a specific content type, set the content_type URI query parameter to the ID you want to search for.

Note: When querying entries and using search filters based on fields or ordering by fields you must specify this parameter. You can only specify one value for content_type at a time.

The select operator allows you to choose what fields to return from an entity. You can choose multiple values by combining comma separated operators.

For example, if you want to return the sys.id and fields.name of an Entry you would use:

/spaces/yadj1kx9rmg0/environments/{environment_id}/entries/?select=sys.id,fields.productName&content_type=2PqfXUJwE8qSYKuM0U6w8M

You can fetch the entire sys or fields object and it's sub-fields by passing it to the select operator. For example to omit the sys object:

/spaces/yadj1kx9rmg0/environments/{environment_id}/entries/?select=fields&content_type=2PqfXUJwE8qSYKuM0U6w8M

The select operator has some restrictions:

• It is only applicable for collections of Entries and Assets, and with an Entry you must provide the content_type query parameter.

• It can only select properties to a depth of 2. For example, select=fields.productName.en-US is not valid.

• If you want to select a property for a specific locale, you need to combine the select and locale operators, e.g /assets/?select=fields.productName&locale=en-US.

• You can select up to 100 properties.

• If you use the select operator on an Entry with linked fields, only the content linked to a field you select will be returned.

If you provide an invalid property path, e.g fields.doesNotExist, Contentful returns a 400 Bad request containing the invalid property path.

You can search for exact matches by using the equality operator. This includes querying an entry by an ID value instead of retrieving the Entry directly, which allows you to include resolved links.

Note: Equality and inequality operators are not supported for text fields and you need to constrain search queries for fields with a content_type URI query parameter.

Uses the [ne] parameter to exclude items matching a certain pattern.

The equality/inequality operators also work with array fields:

• Equality: If one of the items in an array matches the searched term, then it returns the entry.

• Inequality: If one of the fields in an array matches the searched term, then the entry is not returned.

Note: As the query filters by a field, you need to specify a content type.

It's possible to use the [all] operator to retrieve entries matching a specific set of values (e.g. fields.likes[all]=flowers,accessories)

You can filter a field by multiple values with the [in] operator. When applied to an array value there must be at least one matching item. Similarly, when including a field value, you need to specify a Content type.

You can filter a field by multiple values with the [nin] operator. When applied to an array value there must be at least one not matching item. Similarly, when including a field value, you need to specify a content type.

You can check for the presence of a field using the [exists] operator. It checks whether a certain field is defined (i.e. it has any value) or not.

If the field is not defined, it will not be present in the JSON payload and the operator will consider it non-existent.

You can pass true or false as a parameter depending on if you want to retrieve entries where the field exists (true) or does not exist (false). Please note that the parameter is case sensitive, True or False are not valid values.

Four range operators are available that you can apply to date and number fields:

• [lt]: Less than.

• [lte]: Less than or equal to.

• [gt]: Greater than.

• [gte]: Greater than or equal to.

When applied to field values, you must specify the content type in the query.

You have available two flavours of full-text search:

• Global, described in this section

• Field scoped, described in the section full-text search on a field

How does global full text search work

There are cases where you want to find all the content resources which contain some particular words (search terms) but you don't know from which content type (for entries) or on which field those terms can be, so you can't use any of the field filters. For cases like these full-text search is the perfect tool for the job. With it you can find all the content resources which match your search terms in any of their text and symbol fields.

Full-text search can be used to find entries, assets or content types. For the remainder of this section we will refer to entries but the same principles and restrictions will apply to the other types.

Which content is looked up during a global full-text search?

All text (both regular and rich text) and symbol fields in all the locales in your environment will be looked up when doing a global full-text search.

How is an entry considered a match?

Before we explain how we identify matches to your search terms we have to explain how these terms are transformed before they are sent to the search engine. After the API has received your query, the input string is sanitized (i.e. some special characters are removed), tokenized (i.e. split into it's constituent parts) and normalized (i.e. guarantee that the tokens satisfy certain constrains, e.g. removing XML tags). Then each of the remaining search tokens is suffixed with a wildcard operator, which implies that full-text search at contentful is left-anchored.

When checking if an entry satisfies the search criteria, the search engine tests if all of the search tokens (i.e. the transformed search terms) can be found in any field in any locale in the entry. This means that an entry can be included in the result set due to matches in different fields and different locales or due to a match in just one field in just one locale. There is also no guarantee about the order in which the search terms can appear in the matching entries. A search for modern red house can be matched with entries which have those words in any possible order (e.g. red ... house ... modern, red ... modern ... house, etc.).

All this combined means that when you for example search for my cat is blue, the search engine will find all the entries where there are words starting with my and cat and is and blue:

• A field with content like my cat is blue will match.

• A field with content like my cat is red will not match.

• A field with content like there is a catastrophic blueberries accident in my town will match.

• A field with content like there is a caterpillar in my house will not match.

• A field with content like this is a picture of a caterpillar and myself wearing a bluejacket will match.

• A field with content like my cat is <b>blue</b> will match.

• A field with content like my cat is <b class="blue">great</b> will not match.

• An entry with a field with content like my house was blue and another field with content like there is a cat will match.

Check below the phrase full-text search section if you are interested on those entries where the given search terms can only be found in one field and in the same order as in the search input.

Check the full-text search on a field section if you are interested only on those entries where the given search terms are in only one field.

Phrase full-text search

By default full-text search queries will take the search tokens and find all those entries where the tokens can be found in any field, in any locale and in any order. There are however cases where you might need a more restrictive search strategy and only get those entries where the matches are in the same order as you specificed in the search and in only one field. To achieve this you can wrap the search terms in double quotes (") to enable phrase search.

When you for example search for "my cat is blue", the search engine will find all the entries where the words my, cat, is and blue are found in that order in one field:

• A field with content like my cat is blue will match.

• A field with content like my cat is <b>blue</b> will match.

• A field with content like blue is the color of my cat will not match.

• A field with content like my caterpillar is blue will not match.

• An entry with a field with content like my house was blue and another field with content like there is a cat will not match.

If you wish you can combine phrase search with the default full-text search behaviour. This can be useful to refine even more the result set. For example a search like "my cat is blue" summer london will match all those entries where the term "my cat is blue" can be found in just one field in one locale and where the terms summer and london can be found in any field in any locale present in the entry (including the field where the phrase was matched).

Other considerations about full-text search

• Full-text search is case insensitive and might return more results than expected.

• A query will ignore search tokens with less than 2 characters.

• When using full text search, make your search terms as specific as possible.

• The [match] operator might return better results.

• Use phrase search when possible as it has better performance.

• For performance reasons it is recommended to use the equality search operator when searching for slugs or text IDs.

For more tips on using full-text search, see our Help Center article.

With the [match] operator you can do a full-text search restricted to the content of a specific field. The way full-text search behaves on one field is the same as in the global full-text search and the documentation for the global full-text search also applies here, with the particularity that matches on other fields of the entries or assets won't be considered. As with the global search, you can enabled phrase search if you wrap the input search terms in double quoutes (").

You can use a proximity search on location-enabled content to find results in a specified geographical area.

Note: Queries that include exact coordinates can't take advantage of our caching layer. With many use cases it should be enough to round the coordinates to 3 decimal places (an accuracy of about 300m), 2 decimal places (an accuracy of about 1km) or more to improve your cache hit rates.

When displaying content on a map it's more resource efficient to retrieve only content that is in the current visible map area. For these cases, use the within operator.

Similar to the 'near me' use case, this lets you search for locations that are within the specific area on the map and can be useful for finding related entries in the vicinity of another entry.

There are two ways to search for nearby locations.

1. Using a bounding rectangle:

To search for locations within a rectangle area object, use the structure field.center[within]=latitude1,longitude1,latitude2,longitude2, where:

• latitude1 and longitude1 refer to the coordinates of the bottom left corner of the rectangle.

• latitude2 and longitude2 refer to the coordinates of the top right corner of the rectangle.

2. Using a bounding circle:

The structure field.center[within]=latitute,longitude,radius will return entries included in the circle with fields.center of the given latitude, longitude and radius (in km).

To search for entries which have a field linking to a specific entry, set the links_to_entry URI query parameter to the ID you want to search for.

NOTE: For most use cases it is more performant to query based on a content type's reference field if the desired content type is known. See Search on references for an example query

To search for entries which have a field linking to a specific asset, set the links_to_asset URI query parameter to the ID you want to search for.

You can order items in the response by specifying the order search parameter. You can use sys properties (such as sys.createdAt) or field values (such as fields.myCustomDateField) for ordering.

Note: You must set the content_type URI query parameter to the ID of the content type you want to filter by. You can only use the following field types with the order parameter:

The following field types do not support the order parameter:

If you don't pass an explicit order value the returned collection items will be ordered descending by publication timestamp (sys.updatedAt) and ascending by id (sys.id). This means that recently published items will appear closer to the top and for those with the same publication timestamp the order will be based on the items' ids.

You can reverse the sort order by prefixing the field with a - symbol.

You can order items by specifying the order parameter with attributes(attribute, attribute2). Prefix the field with a - sign to reverse the sort order of the attribute.

You can specify the maximum number of results as a limit search parameter.

Note: The maximum number of entries returned by the API is 1000. The API will throw a BadRequestError for values higher than 1000 and values other than an integer. The default number of entries returned by the API is 100.

You can specify an offset with the skip search parameter.

Note: The API will throw a BadRequestError for values less than 0 or values other than an integer.

By combining skip and limit you can paginate through results:

Page 1: skip=0, limit=15 Page 2: skip=15, limit=15 Page 3: skip=30, limit=15 etc.

You can filter assets by their MIME type group by using the mimetype_group query parameter. Valid groups are attachment, plaintext, image, audio, video, richtext, presentation, spreadsheet, pdfdocument, archive, code and markup. By default, the API will return all assets.

You can search for entries based on the values of referenced entries.

For example, if you want to find products of a particular brand, you can use search on references to find the products with one API request.

Structure of a query

Here's how the example above would look as a query:

content_type=2PqfXUJwE8qSYKuM0U6w8M&fields.brand.sys.contentType.sys.id=sFzTZbSuM8coEwygeUYes&fields.brand.fields.companyName[match]=Lemnos

• First is the content_type parameter which you must include when you want to filter based on the values of the fields of entries of a certain content type.

• Second is fields.brand.sys.contentType.sys.id=sFzTZbSuM8coEwygeUYes which you use to to filter on fields of entries from content type 2PqfXUJwE8qSYKuM0U6w8M.

• Third is fields.brand.fields.companyName[match]=Lemnos which filters entries to those branded as 'Lemnos'.

Note: All filters on referenced entries are scoped with the path to the field that contains the reference. In the previous example that path is fields.brand.

You can search on multiple references at once and combine them into one singe API query with a series of field and value pairs.

Available nested filters

You can use the all, in, nin, exists, match, gt, gte,lt, lte, ne, near and within filters when searching on references. The semantics of these filters are the same as when you use them on a non referenced entry.

Restrictions

Searching on references has the following restrictions:

• You can only search on references on fields which link to a single entry. Fields which hold references to many entries or fields with references to assets are not supported.

• The maximum number of reference searches in one query is 2. A larger value will return an error.

You can specify a locale for entries using the locale URI query parameter.

The locale parameter must be the code of a locale in the space you're querying, or the wildcard value *. If you don't specify a locale, the default locale of the space is used.

If there's no content available for the requested locale the API will try the fallback locale of the requested locale.

For example you have the de-CH (Swiss German) locale and configure it to fallback to de-DE (German). When you request content for de-CH any missing field in that locale will be replace with its fallback value in de-DE (if they exist). For more information about locale fallbacks read the locale section of the CMA docs.

When you specify locale=*, field values are nested in an object with keys corresponding to each locale with a defined value. Instead of writing fields.productName when accessing the response data from your code, use fields.productName[localeCode].

If the result contains only a single locale, resources will include the property sys.locale indicating the locale of that object.

Learn more about locales in our concepts document.