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.

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

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.

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.

It's possible to perform a full-text search across all text and symbol fields with the query parameter.

Note: Full-text search is case insensitive and might return more results than expected. A query will only take values with more than 1 character.

You can perform a full-text search on a specific field with the [match] operator.

Note: Full-text search is case insensitive and might return more results than expected. A query will only take values with more than 1 character.

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.

A client syncs content by using the sync endpoint. A single sync consists of one or more pages, each a separate request and response.

The first time a client synchronizes content it sends a request to the sync endpoint with the URI query parameter initial set to true.

You should only sync with initial=true for the initial sync when a client has no existing content. This transfers all content from a space, but does not contain content deleted from fields or deleted assets and content entries.

The limit parameter sets the page size for the number of retrieved entries. The limit is useful when you have very large content entries and reach the maximum response size limit. This limit is then encoded in the synchronization token and used for all following synchronizations.

Sync only contains content from the master environment and is not containing deltas from sandbox environments.

For entries, you can also specify a content_type parameter. When specifying content_type you must specify type as Entry (meaning there will be no deletions). You can only specify the type and content_type parameter at the initial sync along with the initial parameter. Any subsequent syncs will only include the types you have specified. If you want to sync entries by content type you should separately subscribe to a Deletion or DeletedEntry sync to be notified when entries are deleted.

Synchronization responses contain either a nextPageUrl or nextSyncUrl attribute. If there is more content for the current sync, nextPageUrl will contain an URL with a sync_token which will retrieve the next page. This continues until you have retrieved all content.

At this point, the response will contain a nextSyncUrl which you use to make requests in the future and retrieve delta updates between the current content on Contentful and what you retrieved with your last sync request. Upon completion, you will receive a new nextSyncUrl which you can again use for future updates.

If a client loses the nextSyncUrl, the client should delete its local content and perform an initial synchronization again.

NOTE: The initial query with sync_token will persist across subsequent syncs.

For deletions, objects of the types DeletedAsset and DeletedEntry are sent. Those do not contain full assets or entries.