Sync API (1.0.0)

Download OpenAPI specification:Download

Kontent.ai Support: support@kontent.ai License: MIT Terms of Service

About Sync API

Sync API is a secure REST API that provides read-only access to your Kontent.ai environment.

Use Sync API to keep content in your apps up to date. Sync API lets you know if your content items changed in Delivery API or Delivery Preview API.

Why use Sync API?

Use Sync API to update content in your apps. Sync API can be especially useful if you need to:

  • Periodically check if there's new content for translation.
  • Rebuild your static site when specific content is changed. For example, to refresh the content preview.
  • Keep your search index current with the latest content.
  • Control when your app reacts to changes. No need to respond to webhooks as they come. Synchronize the changes in an interval that suits you best.
  • Keep content synchronization async. If your app gets offline occasionally, you can fetch and process updates when online. You can also choose the type of synchronized content by specifying filters.

Sync API compared to webhooks

Both webhooks and Sync API are tools to react to changes in your live and preview content. You can use them together or separately.

Webhooks give you real-time notifications about changes in your content items. Webhooks are great if you need immediate updates. For example, when reporting the latest news or advancements in a sports match. However, immediate updates also mean your app must always be available to process those updates quickly and respond to them. This might be an issue if your app receives a lot of webhook notifications at once.

With Sync API, you get a list of recently changed content items. These can be changes to any content item in any language or a specific type of localized content. You call Sync API in intervals that fit your use case and process the content changes as necessary.

Authentication

BearerAuthentication

Sync API is built on top of Delivery REST API. If you enable secure access for Delivery REST API or want to sync changes in preview content, you need to authenticate your synchronization requests with a valid Delivery API key.

If your use case requires authentication, send your sync requests over HTTPS and use the Authorization header in the following format: Authorization: Bearer <YOUR_API_KEY>. To create and manage your API keys, go to Kontent.ai > Project settings > API keys. Requests with an incorrect or missing Authorization header will fail with an error.

Security Scheme Type: HTTP
HTTP Authorization Scheme bearer
Bearer format: "<YOUR_API_KEY>"

Postman collection

Try the Kontent.ai APIs in Postman collection! Our Postman collection is regularly updated and contains endpoints for all Kontent.ai APIs.

Import the Postman collection

We recommend that you fork the Kontent.ai APIs collection. Forking lets you stay up to date by pulling updates when needed.

Once you import the collection, you can start sending requests. Make sure to use environment variables for API keys.

Use environment variables

Postman environments are sets of variables with specific values. You can use these variables everywhere in your requests in Postman.

For instance, the Kontent.ai APIs collection comes with an environment called Kontent.ai APIs sample values. The environment specifies a variable named environment_id, which is used in all requests. To get started quickly, we recommend you change the environment_id value to the ID of your own environment.

SDKs

You can synchronize your changes via the JavaScript Delivery SDK or .NET Delivery SDK. However, you don’t need an SDK to use the API.

If you want to create your own SDK, see our guidelines for SDK developers.

API limitations

API requests limit

Sync API works on top of Delivery API. Sync requests for changes in published and unpublished content, i.e., Delivery API and Delivery Preview API, count towards the overall API Calls limit set in our Fair Use Policy or your subscription plan.

There is no limit on the total number of API calls you can make.

Rate limitation

Rate limits specify the number of requests you can make to Sync API within a specific time window.

For cached requests served from our CDN, we don't enforce any rate limits. These are repeated requests for cached data.

For uncached requests that reach Sync API, we enforce a rate limitation of 100 requests per second and 2000 requests per minute. These are unique requests for uncached data.

When you reach the rate limit, the API rejects the request and responds with a 429 HTTP error. This error comes with the Retry-After header that tells you how many seconds you need to wait before retrying your request. Each failed request is perfectly safe to retry. If you begin to receive 429 errors, reduce the frequency of your requests.

Errors

The API returns standard HTTP status codes to indicate the success or failure of a request. In general, status codes in the 2xx range indicate a successful request, status codes in the 4xx range indicate errors caused by an incorrect input (for example, providing incorrect API key), and status codes in the 5xx range indicate an error on our side.

HTTP status codes summary

Status code Description
400 Bad Request The request was not understood. Check if your request is missing a required parameter or contains an invalid query parameter value.
401 Unauthorized The provided API key is doesn't provide access to the requested resource. The error can also occur if the API key is malformed or missing. Try copying and pasting your current API key to avoid typos.
403 Forbidden The provided API key is valid but doesn't provide permission for the specified resource.
404 Not Found The requested resource doesn't exist. Try checking the resource name for typos.
405 Method Not Allowed The requested HTTP method is not supported for the specified resource.
429 Too Many Requests The rate limit for the API has been exceeded. Try your request again after a few seconds as specified in the Retry-After header.
5xx Internal Error or Service Unavailable Something went wrong on our side. Try your request again after a few seconds and use a retry policy.

Resolving errors

For troubleshooting failed requests, the API provides error messages defined in a consumable format to help you identify and fix the issue.

Error object in Delivery API.

message
required
string

The error message explaining what caused the error.

request_id
string or null

The performed request's unique ID.

error_code
integer <int32> [ 1 .. 500 ]

The internal error code for the type of error. Used for finding patterns among error requests.

specific_code
integer <int32>

Only useful for finding reasons behind failed requests in specific cases.

{
  • "message": "The continuation token specified in the 'X-Continuation' request header is malformed.",
  • "request_id": "d9b4b4e4750ee210",
  • "error_code": 107,
  • "specific_code": 0
}

If you cannot identify and resolve an issue with your API call, you can contact us with the response status and the request ID you get in the error response.

Guidelines on handling changes

The state of the Sync API may change in the future. However, the majority of the changes won't be breaking changes.

To create more robust scripts and integrations, we recommend you get familiar with the list of general changes to the API that aren't considered breaking. Make sure your app doesn't rely on a state that might change in the future. In general, the non-breaking changes include adding functionality or changes in the order of the returned data.

The following are NOT breaking changes:

  • General:
    • Add a new endpoint.
    • Change the API behavior to fix a bug in the service.
    • Change the rate limitation.
    • Change error message text.
  • Responses:
    • Add a new property to JSON objects.
    • Change the order of JSON object properties.
    • Add a new type of change.
    • Add a new response header.
    • Add a body to a request that contained none.
  • Requests:
    • Add a new optional property to JSON objects.
    • Add a new optional request header.
    • Add a new optional query string parameter.
    • Add a new filtering operator.
    • Add an optional body to a request that contained none.

Filtering

When initializing content synchronization, you can filter the content you want to synchronize by language, content type, and collection.

Filtering operators

Use the following filtering operators to clearly specify the content you want to sync. For filtering by language, only the equal sign operator (=) is allowed. The filtering operators are case-sensitive.

Operator Description Example
Equals to [eq] and = Property value is equal to the specified operator value. language=en-US system.type[eq]=article system.collection[eq]=default
Doesn't equal to [neq] Property value is not equal to the specified operator value. system.type[neq]=article system.collection[neq]=default
Matches one from the list [in] Property value is equal to one of the values in the specified list of values. system.type[in]=article,post system.collection[in]=global,campaigns
Matches none from the list [nin] Property value is not equal to any of the values in the specified list of values. system.type[nin]=home,page system.collection[nin]=global,campaigns

Synchronization

When you synchronize changes, you get a list of delta updates for each content item that has been changed or deleted since the last synchronization. A delta update is similar to a webhook notification, it provides metadata about the changed content item.

When you receive updates from the Sync API, the items contain only system and elements properties, not the modular content.

Sync API sends only the last change type

For example, when a content item has been changed and then deleted, you only get change_type: "deleted" in the Sync API response, not the previous changes.

How to sync changes

Synchronize recent changes in your content items by following these steps:

  1. Initialize a content synchronization. When initializing, you can specify the content types, collections, and the language of the content items you want to sync.
  2. Store the X-Continuation token from the initialization response. This token identifies your content synchronization and its parameters.
  3. Get delta updates and process them.
    1. Synchronize recent changes using the X-Continuation token.
    2. Process the changes.
    3. Store the X-Continuation token from the sync response.
  4. Repeat step 3 until you get an empty sync response.

When there aren't any more changes to synchronize, you should wait a while before synchronizing again (step 3). The wait time depends on your use case. It can be five minutes, an hour, or a day.

Content item delta object

Metadata specifying a content item in a specific language and the time of the item's last change.

change_type
string

Determines whether the content item was modified or deleted since the last synchronization.

Enum Value Description
changed_item

The content item was added or modified in Delivery API.

deleted_item

The content item was deleted from Delivery API.

timestamp
string <date-time>

ISO-8601 formatted date and time in UTC of the last change to the content item. The timestamp identifies when the change occurred in Delivery API.

object

The affected content item.

{
  • "change_type": "changed",
  • "timestamp": "2022-10-20T13:03:06.1310204Z",
  • "data": {
    • "system": {
      • "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb",
      • "collection": "default",
      • "name": "My article",
      • "codename": "my_article",
      • "language": "en-US",
      • "type": "article",
      • "sitemap_locations": [ ],
      • "last_modified": "2019-03-27T13:21:11.38Z",
      • "workflow": "default",
      • "workflow_step": "published"
      },
    • "elements": {
      • "author": {
        • "type": "modular_content",
        • "name": "Author",
        • "value": [
          ]
        },
      • "url": {
        • "type": "url_slug",
        • "name": "URL pattern",
        • "value": "writing-good-error-messages"
        }
      }
    }
}

Initialize content synchronization

post/{environment_id}/sync/init

Initializes synchronization of changes in content items based on the specified parameters. After the initialization, you'll get the X-Continuation token found in the HTTP headers. Use the token to synchronize changes in the content items matching the initialization criteria.

If you don't specify any initialization parameters, content synchronization will be initialized for all content items in all languages in the specified environment.

You can follow the rest of the steps on how to sync changes.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
query Parameters
system.type
string

Specifies the content types of the content items you want to sync. The content types are specified using their codenames. Check the available filtering operators you can use.

If the content type codename is changed after the initialization, you need to initialize a new sync. For example, if you sync changes for items based on the type article and the type codename is later renamed to news_article, there won't be any content items based on the type article anymore. In such case, the API returns an empty response.

Example: system.type=article
system.collection
string

Specifies the collections of the content items you want to sync. The collections are specified using their codenames. Check the available filtering operators you can use.

If you filter your sync to a specific collection, content items moved outside that collection won't appear in API response. For example, if you sync changes for items in the Default collection and a content item moves to an other collection, the content item is no longer in the Default collection and doesn't match the initial sync criteria.

Example: system.collection=article
language
string

Determines the language of content items you want to sync. Language is specified using its codename. If you omit language, the synchronization is initialized for content items in all languages.

Sync API follows language fallbacks as configured in the Localization settings. This means the API might return changes in content items outside the specified language. For example, when you sync content items in Spanish and the Spanish language falls back to English, you can get changes for English content items if some of the content items aren't translated to Spanish yet.

Example: language=en-US
system.language
string

Determines the language of the content items you want to sync. Language is specified using its codename. The API returns changes only for content items in the specified language. Language fallbacks are ignored.

If you omit system.language, the synchronization is initialized for content items in all languages.

Example: system.language=en-US
Responses
200

Content synchronization was initialized.

400

The provided continuation token is invalid.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
const KontentDelivery = require('@kontent-ai/delivery-sdk');

const deliveryClient = KontentDelivery.createDeliveryClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>'
});

const response = await deliveryClient.initializeSync().toPromise();

// Store the X-Continuation token in a persistent storage for later use
const continuationToken = response.xContinuationToken;
Response samples
application/json
{
  • "items": [ ]
}

Synchronize changes in content items

get/{environment_id}/sync

Retrieve a list of delta updates to recently changed content items. The types of items you get is determined by the X-Continuation token you use.

You can follow the rest of the steps on how to sync changes.

SecurityHTTP: BearerAuthentication
Request
path Parameters
environment_id
required
string

Identifies your environment.

Example: 975bf280-fd91-488c-994c-2f04416e5ee3
header Parameters
X-Continuation
required
string

Determines which content changes to synchronize next. You get a new X-Continuation token every time you initialize a content synchronization or synchronize recent changes.

Example: eyJwcm9qZWN0X2lkIjoiNGE4YjQ0ZmEtNzg1Yy0wMGFlLTRkNWMtMDI5ZGU3NDI4Y2FiIiwidGltZXN0YW1wIjoiMjAyMi0xMC0yMFQwOTo1MzozMC4wMTA3MjAxWiIsImZpbHRlciI6IiIsInZlcnNpb24iOiIxLjAifQ==
Responses
200

Delta updates of content items that changed since the previous sync

400

The provided continuation token is invalid.

Request samples 
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
const KontentDelivery = require('@kontent-ai/delivery-sdk');

const deliveryClient = KontentDelivery.createDeliveryClient({
  environmentId: '<YOUR_ENVIRONMENT_ID>'
});

const response = await deliveryClient.syncChanges().toPromise();

// Store the X-Continuation token in a persistent storage for later use
const continuationToken = response.xContinuationToken;

for (const item of response.data.items) {
  if (item.changeType === "changed") {
    // Add logic for case when a content item is changed
  } else if (item.changeType === "deleted") {
    // Add logic for case when a content item is deleted
  }
}

// Synchronize the next batch of changes
const nextResponse = await deliveryClient.syncChanges().withContinuationToken(continuationToken).toPromise();
Response samples
application/json
{
  • "items": [
    • {
      • "change_type": "changed_item",
      • "timestamp": "2023-04-12T13:03:06.1310204Z",
      • "data": {
        • "system": {
          },
        • "elements": {
          }
        }
      },
    • {
      • "change_type": "deleted_item",
      • "timestamp": "2023-04-12T13:06:06.4210204Z",
      • "data": {
        • "system": {
          },
        • "elements": {
          }
        }
      }
    ]
}