Sync API v2 (2)

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

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. These can be changes to content items, content types, languages, or taxonomy groups. 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.

Synchronization

When you synchronize changes, you get a list of delta updates for each entity 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 entity.

When you receive updates from the Sync API, the response contains only the system property for each entity, and you can use further Delivery API calls to get more information.

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. 
  2. Store the X-Continuation token from the initialization response. This token identifies your content synchronization.
  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
required
string

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

Enum Value Description
changed

The content item was added or modified in Delivery API.

deleted

The content item was deleted from Delivery API.

timestamp
required
string

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.

required
object

The affected content item's metadata.

{
  • "change_type": "changed",
  • "timestamp": "2025-06-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"
      }
    }
}

Content type delta object

Metadata specifying a content type and the time of the type's last change.

change_type
required
string

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

Enum Value Description
changed

The content type was added or modified in Delivery API.

deleted

The content type was deleted from Delivery API.

timestamp
required
string <date-time>

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

required
object

The affected content type's metadata.

{
  • "change_type": "changed",
  • "timestamp": "2025-06-20T13:03:06.1310204Z",
  • "data": {
    • "system": {
      • "id": "b2c14f2c-6467-460b-a70b-bca17972a33a",
      • "name": "Article",
      • "codename": "article",
      • "last_modified": "2019-10-20T12:03:17.4685693Z"
      }
    }
}

Language delta object

Metadata specifying a language and the time of its last change.

change_type
required
string

Determines whether the language was modified or deactivated since the last synchronization.

Enum Value Description
changed

The language was added or modified in Delivery API.

deleted

The language was deactivated or deleted from Delivery API.

timestamp
required
string <date-time>

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

required
object

The metadata of the affected language.

{
  • "change_type": "changed",
  • "timestamp": "2025-06-20T13:03:06.1310204Z",
  • "data": {
    • "system": {
      • "id": "00000000-0000-0000-0000-000000000000",
      • "name": "Default language",
      • "codename": "default"
      }
    }
}

Taxonomy group delta object

Metadata specifying a taxonomy group and the time of its last change.

change_type
required
string

Determines whether the taxonomy group was modified or deleted since the last synchronization.

Enum Value Description
changed

The taxonomy group or its terms were added or modified in Delivery API.

deleted

The taxonomy group was deleted from Delivery API.

timestamp
required
string <date-time>

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

required
object

The affected taxonomy group's metadata.

{
  • "change_type": "changed",
  • "timestamp": "2025-06-20T13:03:06.1310204Z",
  • "data": {
    • "system": {
      • "id": "f30c7f72-e9ab-8832-2a57-62944a038809",
      • "name": "Programming language",
      • "codename": "programming_language",
      • "last_modified": "2019-08-31T09:41:06.520241Z"
      }
    }
}

Initialize content synchronization

post/{environment_id}/sync/init

Initializes synchronization of changes in all of the supported entities. After the initialization, you’ll get the X-Continuation token found in the HTTP headers. Use the token to synchronize changes in the entities.

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
Responses
200

Content synchronization was initialized.

Request samples 
// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Delivery;

// Tip: Use DI to create Delivery client https://kontent.ai/learn/net-register-client
IDeliveryClient client = DeliveryClientBuilder
    .WithEnvironmentId("KONTENT_AI_ENVIRONMENT_ID")
    .Build();

// Gets the continuation token based on the given parameters
IDeliverySyncV2Response response = await client.PostSyncV2InitAsync()
    
string continuationToken = response.ApiResponse.ContinuationToken;
Response samples
application/json
{
  • "items": [ ],
  • "types": [ ],
  • "languages": [ ],
  • "taxonomies": [ ]
}

Synchronize changes

get/{environment_id}/sync

Retrieve a list of delta updates to recently changed entities. 

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: G3sAAMTSTeVP97uW0ag9FMER8iRdLEnvTPtQG9jumJHh9Twl6xfy6zqQVMbSKJdIKWhrxjCOc5Jg8IWRoaV2JB3pWEiXjckqcCODtSqVYFiP+10eZIBhMTdkaC7xAw==
Responses
200

Delta updates of entities that changed since previous sync.

400

The provided continuation token is invalid.

Request samples 
// Tip: Find more about .NET SDKs at https://kontent.ai/learn/net
using Kontent.Ai.Delivery;

// Tip: Use DI to create Delivery client https://kontent.ai/learn/net-register-client
IDeliveryClient client = DeliveryClientBuilder
    .WithEnvironmentId("KONTENT_AI_ENVIRONMENT_ID")
    .Build();

// Gets a list of recently changed content items
IDeliverySyncResponse response = await client.GetSyncV2Async("KONTENT_AI_CONTINUATION_TOKEN");
IList<ISyncV2Item> syncItems = response.SyncItems;
IList<ISyncV2ContentType> syncTypes = response.SyncTypes;
IList<ISyncV2Taxonomy> syncTaxonomies = response.SyncTaxonomies;
IList<ISyncV2Language> syncLanguages = response.SyncLanguages;
Response samples
application/json
{
  • "items": [
    • {
      • "change_type": "changed",
      • "timestamp": "2025-05-28T05:33:58.6348403Z",
      • "data": {
        • "system": {
          }
        }
      },
    • {
      • "change_type": "deleted",
      • "timestamp": "2025-05-28T09:11:42.3361261Z",
      • "data": {
        • "system": {
          }
        }
      }
    ],
  • "types": [
    • {
      • "change_type": "changed",
      • "timestamp": "2025-05-28T09:10:46.2792473Z",
      • "data": {
        • "system": {
          }
        }
      }
    ],
  • "taxonomies": [
    • {
      • "change_type": "changed",
      • "timestamp": "2025-05-28T09:10:58.9337234Z",
      • "data": {
        • "system": {
          }
        }
      }
    ],
  • "languages": [
    • {
      • "change_type": "deleted",
      • "timestamp": "2025-05-28T09:11:28.7212524Z",
      • "data": {
        • "system": {
          }
        }
      }
    ]
}