Preview API
Introduction
In addition to the Content Delivery API (CDA) for published content, is the Preview API for previewing both published and unpublished content. It maintains the same behaviour and parameters as the CDA, but delivers the latest drafts for entries and assets. The Content Preview API is used to display the latest version of an entry.
Basic API information
https://preview.contentful.com
Preview API authentication
You authenticate with the Preview API in the same way as the CDA, but using a preview access token.
Your production access tokens will not work with the Preview API. The use of a separate token helps prevent accidentally leaking unpublished content. Every delivery API key has an associated preview access token, which you can view in the APIs tab of a space in the Contentful web app.
Using the Preview API
You use the Preview API as though it were the CDA, but replacing the hostname cdn.contentful.com
with preview.contentful.com
, and the production access token with a preview access token.
It is possible to configure a default preview environment for your entries. This guide includes examples for the generic app, custom and local preview environments.
Preview API limitations
The Preview API does not implement the Sync API, so applications that rely exclusively on the Sync API to load data will not be usable with the Preview API.
API rate limits
API Rate limits specify the number of requests a client can make to Contentful APIs in a specific time frame. Every request counts against a per second rate limit.
By default the Contentful Preview API enforces rate limits of 14 requests per second. Higher rate limits may apply depending on your current plan.
When a client gets rate limited, the API responds with the 429 Too Many Requests HTTP status code and sets the X-Contentful-RateLimit-Reset
header that tells the client when it can make its next request. The value of this header is an integer specifying the time before the limit resets and another request will be accepted.
As the client is rate limited per second, the header will return 1, which means the next second.
Example:
The current rate limits for a client are the default 14 per second.
Example 1
Client: 21 requests in 1 second
HTTP/1.1 429
X-Contentful-RateLimit-Reset: 1
Meaning: wait 1 second before making more requests.
Example 2
Client: 72,000 requests in 15 minutes:
HTTP/1.1 429
X-Contentful-RateLimit-Reset: 3600
Meaning: wait 1 hour before making more requests.
Example 3
Client: 100 requests in 15 mins, 0 requests in following 15 mins, 0 requests in following 15 mins, 71,000 requests in following 15 mins
HTTP/1.1 429
X-Contentful-RateLimit-Reset: 900
Meaning: wait 15 mins before making more requests (which frees up 100 requests - 45 mins later 71,000 requests freed up).
Common resource attributes
Every resource returned by the Preview API will have a sys
property, which is an object containing system managed metadata. The exact metadata available depends on the resource type, but at minimum it defines the sys.type
property.
Note: None of the sys
fields are editable and you can only specify the sys.id
in the creation of an item (If it's not a *space_).
Contentful defines the sys.id
property for every resource that is not a collection. For example, a Space
resource will have a sys.type
and sys.id
:
{
"sys": {
"type": "Space",
"id": "yadj1kx9rmg0"
}
}
Field | Type | Description | Applies to |
---|---|---|---|
sys.type | String | Resource type. | All |
sys.linkType | String | Type of an entity the link is referring to. | Links |
sys.id | String | Unique ID of resource. | All except arrays |
sys.space | Link | Link to resource's space. | Entries, assets, content types |
sys.environment | Link | Link to a resource's environment. | Entries, assets, content types |
sys.contentType | Link | Link to entry's content type. | Entries |
sys.revision | Integer | Publish counter of the resource. | Entries, assets, content types |
sys.createdAt | Date | Date and time a resource was generated in the system. | Entries, assets, content types |
sys.updatedAt | Date | Date and time a resource was updated in the system. | Entries, assets, content types |
sys.locale | String | Locale of a resource. | Entries and assets |
sys.publishedVersion | Integer | Published version of the resource | Entries, assets, content types |
sys.firstPublishedAt | Date | Date and time a resource was first published | Entries, assets, content types |
sys.publishedAt | Date | Date and time a resource was published | Entries, assets, content types |
Note: The revision
field refers to the current number of published revisions of an entry. Find out more in the Content Management API documentation.
Some of sys
properties, while having the same label, render different kinds of data depending on the API. Please see the descriptions of these properties per API in the table below:
Property name per API | Description | ||
---|---|---|---|
CMA | CDA | CPA | |
firstPublishedAt | createdAt | - | Date and time a resource was published for the first time. |
publishedAt | updatedAt | - | Date and time a resource was published after an update. |
createdAt | - | createdAt | Date and time a resource was generated in the system. |
updatedAt | - | updatedAt | Date and time a resource was updated in the system. |
Collection resources and pagination
Contentful returns collections of resources in a wrapper object that contains extra information useful for paginating over large result sets:
{
"sys": { "type": "Array" },
"skip": 0,
"limit": 100,
"total": 1256,
"items": [ /* 100 individual resources */ ]
}
In the above example, a client retrieves the next 100 resources by repeating the same request, changing the skip
query parameter to 100
. You can use the order
parameter when paging through larger result sets to keep ordering predictable. For example, order=sys.createdAt
will order results by the time the resource was first published.
Reference
Spaces
All content and assets in Contentful belong to a space. You will generally have at least one space for a project, but use separate spaces for testing or staging.
Space
Each space has a name, a set of locales, and metadata about the space.
Get a space
Content types
Defining a content type is a fundamental step in powering your applications with Contentful. A content type consists of a set of fields and other information, read this guide to learn more about modeling your content.
Content model
Get the content model of a space
Content type
Get a single content type
Entries
Entries represent anything defined as a Content Type in a space.
Entries can have link fields that point to other entries or assets. You can learn more about links in our concept guide.
Entry object description
Entry object consists of the following top-level properties:
Field | Type | Description |
---|---|---|
metadata | Metadata | User-controlled metadata. Note: Currently holds tags and concepts property, which contains lists of tags and taxonomy concepts assigned to an entry, respectively. |
sys | Sys | Common system properties. For detailed description of properties, please refer to Common resource attributes. |
fields | Object | Fields that are custom defined by a user through the definition of content types.fields object in CDA and/or CPA includes locale only when it is specifically requested in an API call or when your content is synchronized via Sync API. Whenever locale is not included, the locale value in the entry object will be returned under the sys.locale property. |
Entries collection
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.
Get all entries of a Space
Entry
The include
array is not applicable while retrieving a single entry.
Get a single entry
Unresolved entries
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"
}
}
]
}
Assets
Assets are the binary files in a space. An asset can be any file type and are usually attached to entries with links.
You can localize assets by providing separate files for each locale. Assets which are not localized are available as a single file under the default locale.
When you query for entries which contain links to assets then all assets are included by default.
Asset properties:
Field | Type | Description |
---|---|---|
sys | Sys | Common system properties. |
fields.title | Text | Title of the asset. |
fields.description | Text | Description of the asset. |
fields.file | File | File(s) of the asset. |
fields.file.fileName | Symbol | Original filename of the file. |
fields.file.contentType | Symbol | Content type of the file. |
fields.file.url | Symbol | URL of the file. |
fields.file.details | Object | Details of the file, depending on its MIME type. |
fields.file.details.size | Number | Size (in bytes) of the file. |
For image assets, the fields.file.url
field will point to images.ctfassets.net
. For other file types, it will point to assets.ctfassets.net
.
For large image assets (greater than 20MB and other asset files greater than 10MB) use the downloads.ctfassets.net
.
You can use query parameters to define the image size, cropping parameters and other options. Find out more in our Images API reference.
For video assets, use videos.ctfassets.net
.
Assets collection
Get all assets of a space
Asset
Get a single asset
Asset keys
Asset keys are used when signing Embargoed Asset URLs. This feature is only enabled for spaces on Premium/Enterprise plans that have enabled Embargoed Assets.
Asset key
Create an asset key
To sign embargoed asset URLs, you need to create an asset key. Secure asset URLs delivered by the CDA, CMA, or CPA will have a host of (images,assets,videos,downloads).secure.ctfassets.net
. They cannot be accessed without first signing the URL.
Signing an embargoed asset URL is accomplished by the following steps:
Create an asset key for the space the asset URL belongs to. You must specify an
expiresAt
value, a Unix epoch timestamp in seconds, and this can be no more than 48 hours in the future.Create a JWT with the embargoed asset URL as the
sub
(JWT subject). Sign the JWT with the asset key'ssecret
.Affix to the original embargoed asset URL the following query parameters:
policy
- the asset key's policytoken
- the JWT created in step 2
You may affix other query parameters as well, for example when using the Images API. These do not impact the validity of the signed URL.
By default, a signed asset URL will stop functioning after the expiresAt
value that was specified when creating the asset key. When generating the JWT, you may optionally specify an exp
(expiry) that will cause the signed URL to be unusable at the specified expiry time. If a per-URL expiry is greater than the expiresAt
value specified when creating the asset key, the asset key's expiresAt
value will be used instead.
Locales
Locales allow you to define translatable content for assets and entries. A locale includes the following properties:
name
: A human readable identifier for a locale. For example, 'British English'.code
: An identifier used to differentiate translated content in API responses. For example, 'en-GB'.fallbackCode
: The code of the locale to use if there is no translated content for the requested locale. For example,en-US
. You can set it tonull
if you don't want a default locale. This can only be set via the API, and not with the web app or client libraries.
Locale collection
Get all locales of a space
The locales endpoint returns a list of all created locales. One will have the flag default
set to true and is the locale used in the CDA, and you specified no other locale in the request.
Taxonomy
Taxonomy on content types
Note:
Content types payload comes with a
metadata
property. This metadata property has as its value ataxonomy
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.
Get a single content type
Returns a single content type with a metadata property. The metadata property holds a list of taxonomy concepts and/or concept schemes.
Taxonomy concepts on entries
Note:
Entry payloads come with a
metadata
property. This metadata property has as its value aconcepts
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.
Get a single entry
Returns a single entry with a metadata property. The metadata property holds a list of taxonomy concepts.
Querying content based on a set of concepts
The query parameter starts with metadata.concepts.sys.id
with operator [all]
.
Retrieve entries that match a set of concepts values
Returns a list of entries according to one or more of the specified concept IDs.
Querying content based on one or more concepts
The query parameter starts with metadata.concepts.sys.id
with operator [in]
.
Retrieve entries that match at least one of the specified concepts values
Returns a list of entries according to the specified set of concept IDs.
Querying content based on one or more concepts and their descendants
The query parameter starts with metadata.concepts.descendants
with operator [in]
.
Retrieve entries that match at least one of the specified concepts values or their descendants
Returns a list of entries according to the specified set of concept IDs and their descendant concepts.
Tags
Tags help you to easily search for specific content in your environment.
Tags are environment-scoped which means that they exist within and are unique to an environment.
Only tags with visibility public
are accessible via the delivery and preview APIs.
To learn more about the different tag visibility options, see the tags visibility documentation in the management api reference page.
A tag includes the following properties:
name: A human-readable unique identifier for the tag
id: A unique identifier for referencing the tag
visibility: A sys property with value
public
that makes the tag accessible via the delivery and preview API
Tag collection
Get all tags
Returns all the tags that exist in a given environment.
Tag
Get a single tag
Returns a single tag based on the given identifier.
Tags on entries and assets
Note:
Entries and assets payload come with a
metadata
property. This metadata property has as its value atags
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.
Get a single entry
Returns a single entry with a metadata property. The metadata property holds a list of tags.
The same behavior applies for assets.
Querying content based on a set of tags
The query parameter starts with metadata.tags.sys.id
with operator [all]
.
Retrieve entries or assets that match a specific set of tag values
Returns a list of entries according to the specified set of tag IDs.
Querying content based on one or more tags
The query parameter starts with metadata.tags.sys.id
with operator [in]
.
Retrieve entries or assets that match at least one of the specified tag values
Returns a list of entries according to one or more of the specified tag IDs.
Querying content based on the tag presence
The query parameter starts with metadata.tags
with operator [exists]
.
Check the presence of a tag on entries or assets
Returns all entries that are assigned with tags.
This parameter value is case sensitive: “True” or “False” are not valid values.
Links
Links are a powerful way to model relationships between content entries and assets. You can learn more about links in our concept guide.
Retrieval of linked items
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
.
Query entries
Links to a specific item
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.
Query entries
Resource Links
Resource Links are part of the Cross-space references feature set that allows you to link content across multiple spaces. It mainly uses ResourceLink
links as a way to represent a relationship between entities from different spaces.
ResourceLink
links are represented as a sys
object containing urn
, linkType
and type
:
Property | Description |
---|---|
sys.linkType |
Represents what kind of entity this resource links to. For cross-space entries the value is Contentful:Entry . |
sys.type |
The type of Link. ResourceLink is the default for cross-space resources. |
sys.urn |
The location of the resource. A CRN to a Contentful environment entity. |
As they are part of another space, resolving cross-space linked entities requires a special header to be passed in each request named x-contentful-resource-resolution
.
Extra header for cross-space resolution
The x-contentful-resource-resolution
header is a base64 encoded JSON object containing key-value pairs of spaceId/API Key. The plain JSON used to create the header should have the following shape:
{
"spaces": {
"someSpaceId": "<access-token>",
"anotherSpaceId": "<access-token>"
}
}
That then needs to be stringified and encoded to base64. You can use JSON.stringify
and btoa
(JavaScript) to properly convert the JSON object to a stringified encoded version of it.
Here is a full example in JavaScript:
const extraTokens = {
"spaces": {
"IdToR3s0lv3": "ND63YKcYBe335RWDnIuzv...",
"4n0th3rSp4c3": "UuVe6icuBuXv..."
}
}
// Converts object to string and uses base64 to encode the string
window.btoa(JSON.stringify(extraTokens)) // eyJzcGFjZXMiOnsiSWRUb1I[...]=
The value can then be passed to the x-contentful-resource-resolution
header as-is. All cross-space references of matching space IDs will be returned within the includes
property of the response.
Capabilities
The
locale
query parameter is propagated to all extra spaces present in the new header.Only the first level of references of every extra space in the new header will be resolved. It applies to only one level of space. This is a behavior similar to
include=1
.The main space (space Id being requested in the URL) will still resolve up to 10 levels.
Publishing new content in any of the extra spaces will cause the cache to be purged on every request that included that space Id.
The
includes
property of the response will include both cross-space entries and assets.You can pass this new header in the Javascript SDK for automatic resolution.
Errors
Errors from cross-space requests are propagated back to the response payload in the errors
property.
If a request to a single cross-space fails, the main space request and other spaces will still continue to process.
HTTP Status Code | Description |
---|---|
401 |
Missing Authorization header |
400 |
Incorrect format for the x-contentful-resource-resolution header. |
400 |
Number of extra spaces in the header exceeds the maximum allowed number (20 ) |
Errors property example
{
"errors": [
{
"details": {
"urn": "crn:contentful:::content:spaces/<spaceId>/environments/<environmentId>/entries/<entryId>",
"linkType": "Contentful:Entry",
"type": "ResourceLink"
},
"sys": {
"id": "notResolvable",
"type": "error"
}
}
]
}
Limitations
Up to
21
spaces to be resolved in a single requestOnly
20
extra space tokens are supported. You can make a single API call that resolves up to21
spaces at the same time:20
extra spaces and the entries from the space Id in the initial request.Up to
1000
references in theincludes
property in the response.Only the first level of cross-space references is resolved from the original spaceId in the URL
The
Authorization
header is still required for every request and it should enable access to the main space Id in the URL.Errors from the extra space tokens will be returned in the
errors
property of the response.Using the new header will also consume the Rate Limiting from the space Ids present in it when the request is uncached.
No Advanced Caching support
No MRDI support
For more information, see the Resource Links FAQs.
Retrieval of linked Resource Links
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
.
Query entries
Search parameters
You can use a variety of query parameters to search and filter items in the response from any collection endpoint including entries, content types and assets.
Content type
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.
Query entries
This example finds all entries of content type 'Product'.
Select operator
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
andlocale
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.
Query entries
To select only the productName
field of each entry.
Equality operator
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.
Query entries
To find all entries with the ID 5KsDBWseXY6QegucYAoacS
(IDs are unique).
Inequality operator
Uses the [ne]
parameter to exclude items matching a certain pattern.
Query entries
To return all entries, except those with the ID 5KsDBWseXY6QegucYAoacS
.
Array equality/inequality
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.
Query entries
This example finds all products tagged as accessories
by matching fields.tags
(an array) against a single value.
Array with multiple values
It's possible to use the [all]
operator to retrieve entries matching a specific set of values (e.g. fields.likes[all]=flowers,accessories
)
Query entries
To find all products tagged as flowers
and accessories
by using the all
operator with fields.tags
(an array) and the two values.
Inclusion
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.
Query entries
To retrieve entries that match accessories
and flowers
.
Exclusion
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.
Query entries
To retrieve all products tagged as neither 'flowers' nor 'accessories'.
Existence
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.
Query entries
To retrieve all entries that have a value for field.tags
defined.
Ranges
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.
Query entries
To retrieve entries updated since midnight of January 1st 2013.
Full-text search
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.
Query entries
To retrieve all entries containing the word 'design'.
Full-text search on a field
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 (").
Query entries
To retrieve all entries which contain words starting with 'content' in the 'website' field.
Location proximity search
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.
Query entries
A common use case for location search is to search for places close to the user's current position.
Use the [near]
operator to show results closest to a specific map location and order the results by distance.
This will return all entries sorted by distance from the point at latitude=38
and longitude=-122
.
Locations in a bounding object
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
andlongitude1
refer to the coordinates of the bottom left corner of the rectangle.latitude2
andlongitude2
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).
Query entries
To retrieve entries where fields.center
is within the rectangle with:
Bottom left corner: latitude 1, longitude 2.
Top right corner: latitude 3, longitude 4.
Links to entry
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
Query entries
Links to asset
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.
Query entries
Order
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:
Name | JSON Primitive | Description |
---|---|---|
Symbol | String | Basic list of characters. Maximum length is 256. |
Integer | Number | Number type without decimals. Values from -253 to 253. |
Number | Number | Number type with decimals. |
Date | String | Date/time in ISO-8601 format. |
Boolean | Boolean | Flag, true or false . |
The following field types do not support the order parameter:
Name | JSON Primitive | Description |
---|---|---|
Text | String | Same as symbol, but can be filtered via full-text search. Maximum length is 50,000. |
Link | Object | See links |
Array | Array | List of values. Value type depends on field.items.type . |
Object | Object | Arbitrary object. |
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.
Query entries
To retrieve all entries ordered by creation date.
Reverse order
You can reverse the sort order by prefixing the field with a -
symbol.
Query entries
To order results by the time of the last update, newest to oldest.
Order with multiple parameters
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.
Query entries
Limit
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.
Query entries
To limit results to 3 entries.
Skip
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.
Query entries
To skips 3 entries.
Filtering assets by MIME type
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.
Query assets
To return only image assets.
Search on references
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 type2PqfXUJwE8qSYKuM0U6w8M
.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.
Search on references
This example will return the Lemnos branded products.
Localization
Retrieve localized entries
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.
Query entries
fields.productName
is the only localized field in the product
content type, so returns all other fields in the default locale.