www.contentful.com Open in urlscan Pro
3.121.122.184  Public Scan

Form analysis
0 forms found in the DOM

Text Content

Developers
 * Developer portal
 * Documentation
 * Changelog
 * Blog
 * Pricing

Select...Developer portalDocumentationChangelogBlogPricing
SIGN UPLOGIN

ConceptsTutorialsPlatformsAPI
referenceExtensibilityWebhooksInfrastructureExperiencesComposeTools and Plugins
 * Introduction
   * Authentication
   * API rate limits
   * Common resource attributes
   * Date and time format
   * Collection resources and pagination
 * Reference
   * Spaces
     * Space
   * Content types
     * Content model
     * Content type
   * Entries
     * Entries collection
     * Entry
     * Unresolved entries
   * Assets
     * Assets collection
     * Asset
   * Asset keys
     * Asset key
   * Locales
     * Locale collection
   * Tags
     * Tag collection
     * Tag
     * Tags on entries and assets
     * Querying content based on a set of tags
     * Querying content based on one or more tags
     * Querying content based on the tag presence
   * Links
     * Retrieval of linked items
     * Links to a specific item
   * Search parameters
     * Content type
     * Select operator
     * Equality operator
     * Inequality operator
     * Array equality/inequality
     * Array with multiple values
     * Inclusion
     * Exclusion
     * Existence
     * Ranges
     * Full-text search
     * Full-text search on a field
     * Location proximity search
     * Locations in a bounding object
     * Links to entry
     * Links to asset
     * Order
     * Reverse order
     * Order with multiple parameters
     * Limit
     * Skip
     * Filtering assets by MIME type
     * Search on references
   * Localization
     * Retrieve localized entries
   * Resource Links
     * Retrieval of linked Resource Links
   * Synchronization
     * Initial synchronization
     * Initial synchronization of entries of a specific content type
     * Pagination and subsequent syncs
     * Structure of deleted entities

Documentation / API reference / Content Delivery API


CONTENT DELIVERY API




INTRODUCTION


Note: The use of Contentful is subject to the Fair Usage Policy and to ensure
uninterrupted functionality of the shared-service infrastructure, adhere to
Technical Limits.

The Content Delivery API (CDA), available at cdn.contentful.com, is a read-only
API for delivering content from Contentful to apps, websites and other media.
Content is delivered as JSON data, and images, videos and other media as files.

The API is available via a globally distributed content delivery network (CDN).
The server closest to the user serves all content, which minimizes latency and
especially benefits mobile apps. Hosting content in multiple global data centers
also improves the availability of content.

You'll need a free Contentful account and Contentful space to get started. You
can sign up here.

Note: For EU data residency customers, the Base URL is
https://cdn.eu.contentful.com.


BASIC API INFORMATION

API Base URL https://cdn.contentful.com
This is a read-only API


AUTHENTICATION



Any client requesting content from the CDA needs to provide an access token that
has access to the environment you're requesting content from. For example, if
you create an access token that only has access to the master environment of
your space, you will not be able to use this token to access content from any
other environment.

You have two options to supply the access token, either as an Authorization
request header field, or as an access_token URI query parameter. The CDA
implements the standardized OAuth 2.0 bearer token specification already
supported by many HTTP clients.

You create access tokens in the APIs tab of each space in the Contentful web
app. Our reference guide has more details on how authentication works with
Contentful.


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.

There are no limits enforced on requests that hit our CDN cache, i.e. the
request doesn't count towards your rate limit and you can make an unlimited
amount of cache hits. For requests that do hit the Content Delivery API, a rate
limit of 55 requests per second is enforced. 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 single 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 limit for a client is the default 55 per second. Client: 85
uncached requests in 1 second

CopyHTTP/1.1 429
X-Contentful-RateLimit-Reset: 1

Meaning: wait 1 second before making more requests.


COMMON RESOURCE ATTRIBUTES



Every resource returned by the Content Delivery 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:

Copy{
  "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 Published version of
resource. Entries, assets, content types sys.createdAt Date Date and time a
resource was published for the first time. Entries, assets, content types
sys.updatedAt Date Date and time a resource was published after an update.
Entries, assets, content types sys.locale String Locale of the resource. Entries
and assets

Note: The revision field refers to the current number of published revisions of
an entry. Find out more in the Content Management API documentation.

Sys properties - difference in meaning in Contentful APIs


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.


DATE AND TIME FORMAT



Date and time must be formatted according to ISO 8601.

Important: When setting time, ensure to indicate timezone. With no timezone
specified, UTC+0 is applied as a default one.

The table below displays the supported date and time formatting:

Data type Format Examples Date only "YYYY-MM-DD" "2015-11-06" Date + time
"YYYY-MM-DDThh:mm:ss"
"YYYY-MM-DDThh:mm:ss.sss" "2015-11-06T09:45" Date + time + timezone
"YYYY-MM-DDThh:mm:ssZ"
"YYYY-MM-DDThh:mm:ss±[hh:mm]" "2015-11-06T09:45:27Z"
"2015-11-06T09:45:27+00:00"
"2015-11-06T09:45:27-08:00"


COLLECTION RESOURCES AND PAGINATION



Contentful returns collections of resources in a wrapper object that contains
extra information useful for paginating over large result sets:

Copy{
  "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 property, which contains list of tags assigned to an
entry.
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:

Copy{
  "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:

 1. 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.

 2. Create a JWT with the embargoed asset URL as the sub (JWT subject). Sign the
    JWT with the asset key's secret.

 3. Affix to the original embargoed asset URL the following query parameters:
    
    * policy - the asset key's policy
    * token - the JWT created in step 2

 4. 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 to null 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.


TAGS


Note: Currently, only a few of our client libraries support Tags. Please ensure
you're using the latest version of the client libraries.

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 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.


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


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:

Copy/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:

Copy/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.


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 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).


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:

Copycontent_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.


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.


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:

Copy{
    "spaces": {
        "someSpaceId": "<cda-token>",
        "anotherSpaceId": "<cda-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:

Copyconst 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 (3)

ERRORS PROPERTY EXAMPLE

Copy{
    "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 4 spaces to be resolved in a single request

 * Only 3 extra space tokens are supported. You can make a single API call that
   resolves up to 4 spaces at the same time: 3 extra spaces and the entries from
   the space Id in the initial request.

 * Up to 1000 references in the includes 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


SYNCHRONIZATION



The Sync API allows you to keep a local copy of all content in a space
up-to-date via delta updates, or only the content that has changed.


SYNCING SPECIFIC CONTENT

By default a sync request response includes all resource types including assets,
entries of all content types and deleted resources.

To sync specific content you can specify a type parameter for the initial sync:

Parameter Description all (default) Include all new and changed content, i.e.,
assets, entries and deletions. Asset Only include new and changed assets. Entry
Only include new and changed entries. Deletion Only include deletions of assets
and entries. DeletedAsset Only include deletions of assets. DeletedEntry Only
include deletions of entries.

INITIAL SYNCHRONIZATION



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.


QUERY ENTRIES

INITIAL SYNCHRONIZATION OF ENTRIES OF A SPECIFIC CONTENT TYPE



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.


QUERY ENTRIES

PAGINATION AND SUBSEQUENT SYNCS



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.


QUERY ENTRIES

STRUCTURE OF DELETED ENTITIES



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


QUERY DELETED ENTRIES


QUERY DELETED ASSETS


ALL TOPICS

Learn more at Contentful.com


CONCEPTS

 * API basics
 * App Framework
 * Domain model
 * Data model
 * Entry and asset links
 * Images
 * Content localization through locales
 * Sync API
 * Multiple environments
 * Environment Aliases
 * Environment support for Cross-space references
 * Environments and environment aliases best practices
 * Webhooks
 * Filter API results with relational queries
 * What is rich text?
 * External references
 * Continuous integration and deployment pipelines


TUTORIALS

 * General
 * CLI
 * JavaScript
 * PHP
 * Android
 * iOS
 * Java
 * Python
 * Ruby
 * .NET


PLATFORMS

 * JavaScript
 * PHP
 * Android
 * iOS
 * Java
 * Python
 * Ruby
 * .NET


API REFERENCE

 * Content Delivery API
 * Content Management API
 * Content Preview API
 * Images API
 * GraphQL Content API
 * User Management API
 * SCIM API
 * Authentication
 * Errors
 * HTTP details
 * App SDK reference


EXTENSIBILITY

 * App Framework
 * Field editors
 * OAuth


WEBHOOKS

 * Overview
 * Content events
 * Action events
 * Configuring a webhook
 * List webhooks in a space
 * Activity log
 * Webhook Templates
 * Request Verification


INFRASTRUCTURE

 * Multi-region delivery infrastructure (MRDI)
 * Advanced caching
 * EU data residency


EXPERIENCES

 * What are Experiences?
 * Set up Experiences SDK
 * Register custom components
 * Component definition schema
 * Built-in styles
 * Design tokens
 * Data structures
 * Error handling
 * Image optimization
 * Using Experiences with NextJS


COMPOSE

 * What is Compose?
 * Customizable Compose content model
 * Page types
 * Known Limitations - Compose
 * Upgrade to customizable Compose content model
 * Content model best practices for Compose
 * Extending and customizing Compose
 * Roles and Permissions for Compose
 * CLI tools and Compose
 * Building a website with Compose in Next.js
 * Frequently Asked Questions
 * Documentation for editors
 * Legacy content model


TOOLS AND PLUGINS

 * Space management
 * Static site generators
 * Automation and developer workflows
 * Command-line interface (CLI)
 * AI Content Type Generator


LEARN MORE


SupportGet started


WEB APP

 * Contentful overview
   
 * Modeling basics
   
 * Creating a digital lookbook
   
 * Localization
   
 * Versioning
   
 * Roles and permissions
   


ADVANCED

 * Webhooks
   
 * CMS as code
   
 * Headless & Decoupled CMS
   


MORE

 * Changelog
 * API Changes
 * Technical limits
 * Code of Conduct
 * Support
   
 * Stack Overflow
   

• All Systems Operational