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 typeFor 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:

Initialize a content synchronization. When initializing, you can specify the content types, collections, and the language of the content items you want to sync.
Store the X-Continuation token from the initialization response. This token identifies your content synchronization and its parameters.
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.
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.

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.

data

object

The content item with metadata and individual elements.

Show child attributes

JSON

{
  "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"
    },
    "<element_codename>": {
      "author": {
        "type": "modular_content",
        "name": "Author",
        "value": [
          "jenny_brown"
        ]
      },
      "url": {
        "type": "url_slug",
        "name": "URL pattern",
        "value": "writing-good-error-messages"
      }
    }
  }
}

Initialize content synchronization

Deprecated

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.

Sync API v1 has been removedSync API v1 was shut down on January 5, 2026. All v1 endpoints are no longer functional. Use Sync API v2 for improved reliability and expanded synchronization for languages, taxonomies, and content types.

POST

https://deliver.kontent.ai/{environment_id}/sync/init

POST

https://preview-deliver.kontent.ai/{environment_id}/sync/init

Request

Path parameters

environment_id

required · string

Identifies your environment.

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.

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.

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.

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.

Request samples

TypeScript
C#
cURL

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { createDeliveryClient } from '@kontent-ai/delivery-sdk';

const deliveryClient = createDeliveryClient({
  environmentId: 'KONTENT_AI_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

Status (200)

Content synchronization was initialized.

items[]

array

List of delta updates for content items that changed since the last content synchronization.When you initialize content synchronization, the items array is always empty.

Hide child attributes

change_type

string

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

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.

data

object

The content item with metadata and individual elements.

Hide child attributes

system

required · object

The content item's system properties.

Hide child attributes

id

required · string · uuid

The content item's internal ID.

collection

required · string

The content item's collection codename. For projects without collections enabled, the value is default.

name

required · string

The content item's display name.

codename

required · string

The content item's codename. By default, generated from the item's display name.

language

required · string

The codename of the language that the content is in.For details on retrieving content in different languages, see Getting localized content.

type

required · string

The codename of the item's type.

sitemap_locations[]

required · array

Deprecated

A list of sitemap locations that the content item is in.

last_modified

required · string · date-time

ISO-8601

formatted date and time of the last change to user-content of the content item.

Moving content items through workflow doesn't affect the last_modified value.

workflow

string

The codename of the content item's current workflow. By default, generated from the workflow's display name.This property is not present for components.

workflow_step

string

The codename of the content item's current workflow step. By default, generated from the workflow step's display name.This property is not present for components.

<element_codename>

object

The item's elements with values for the specific language. The order of the element objects might not match the content element order in the UI.

Hide child attributes

required · nestedSchema

Any of:

Asset element

Custom element

Date and time element

Linked items element

Multiple choice element

Number element

Rich text element

Subpages element

Taxonomy element

Text element

URL slug element

Asset element

type

required · string

The element's type.

name

required · string · 1-50 chars

The element's display name.

value[]

required · array

The assets inserted into the element. The asset objects are returned in the same order as shown in the UI.Some of the properties are specific to images only: width and height represent the image’s width and height dimensions, and the renditions object contains details about customized images. To display customized images on the website or an app, you first need to apply custom query parameters to the asset’s original URL.

Show child attributes

Example responses

200
400

{
  "items": []
}

Synchronize changes in content items

Deprecated

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.

GET

https://deliver.kontent.ai/{environment_id}/sync

GET

https://preview-deliver.kontent.ai/{environment_id}/sync

Request

Path parameters

environment_id

required · string

Identifies your environment.

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.

Request samples

TypeScript
C#
cURL

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { createDeliveryClient } from '@kontent-ai/delivery-sdk';

const deliveryClient = createDeliveryClient({
  environmentId: 'KONTENT_AI_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') {
    // Process a changed item
  } else if (item.changeType === 'deleted') {
    // Process a deleted item
  }
}

// Synchronize the next batch of changes
const nextResponse = await deliveryClient
  .syncChanges()
  .withContinuationToken(continuationToken)
  .toPromise();

Response

Status (200)

Delta updates of content items that changed since the previous sync

items[]

array · max. 500 items

List of delta updates for content items that changed since the last content synchronization.If there haven't been any changes, the items array is empty.

Hide child attributes

change_type

string

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

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.

data

object

The content item with metadata and individual elements.

Hide child attributes

system

required · object

The content item's system properties.

Hide child attributes

id

required · string · uuid

The content item's internal ID.

collection

required · string

The content item's collection codename. For projects without collections enabled, the value is default.

name

required · string

The content item's display name.

codename

required · string

The content item's codename. By default, generated from the item's display name.

language

required · string

The codename of the language that the content is in.For details on retrieving content in different languages, see Getting localized content.

type

required · string

The codename of the item's type.

sitemap_locations[]

required · array

Deprecated

A list of sitemap locations that the content item is in.

last_modified

required · string · date-time

ISO-8601

formatted date and time of the last change to user-content of the content item.

Moving content items through workflow doesn't affect the last_modified value.

workflow

string

The codename of the content item's current workflow. By default, generated from the workflow's display name.This property is not present for components.

workflow_step

string

The codename of the content item's current workflow step. By default, generated from the workflow step's display name.This property is not present for components.

<element_codename>

object

The item's elements with values for the specific language. The order of the element objects might not match the content element order in the UI.

Hide child attributes

required · nestedSchema

Any of:

Asset element

Custom element

Date and time element

Linked items element

Multiple choice element

Number element

Rich text element

Subpages element

Taxonomy element

Text element

URL slug element

Asset element

type

required · string

The element's type.

name

required · string · 1-50 chars

The element's display name.

value[]

required · array

Show child attributes

Example responses

200
400

{
  "items": [
    {
      "change_type": "changed_item",
      "timestamp": "2023-04-12T13:03:06.1310204Z",
      "data": {
        "system": {
          "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb",
          "collection": "default",
          "name": "Hello World",
          "codename": "hello_world",
          "language": "en-US",
          "type": "article",
          "sitemap_locations": [],
          "last_modified": "2019-03-27T13:21:11.38Z",
          "workflow": "default",
          "workflow_step": "published"
        },
        "elements": {
          "title": {
            "type": "text",
            "name": "Title",
            "value": "Hello World"
          }
        }
      }
    },
    {
      "change_type": "deleted_item",
      "timestamp": "2023-04-12T13:06:06.4210204Z",
      "data": {
        "system": {
          "id": "363d17ac-b6ba-4c6a-ae53-27c1172515cb",
          "collection": "default",
          "name": "Goodbye World",
          "codename": "bye_world",
          "language": "en-US",
          "type": "article",
          "sitemap_locations": [],
          "last_modified": "2019-03-27T13:21:11.38Z",
          "workflow": "default",
          "workflow_step": "published"
        },
        "elements": {
          "title": {
            "type": "text",
            "name": "Title",
            "value": "Goodbye World"
          }
        }
      }
    }
  ]
}

How to sync changes

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

Initialize a content synchronization. When initializing, you can specify the content types, collections, and the language of the content items you want to sync.

Store the X-Continuation token from the initialization response. This token identifies your content synchronization and its parameters.

Get delta updates and process them.

Synchronize recent changes using the X-Continuation token.
Process the changes.
Store the X-Continuation token from the sync response.

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.

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.

data

object

The content item with metadata and individual elements.

Show child attributes

JSON

{
  "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"
    },
    "<element_codename>": {
      "author": {
        "type": "modular_content",
        "name": "Author",
        "value": [
          "jenny_brown"
        ]
      },
      "url": {
        "type": "url_slug",
        "name": "URL pattern",
        "value": "writing-good-error-messages"
      }
    }
  }
}

Initialize content synchronization

Deprecated

POST

https://deliver.kontent.ai/{environment_id}/sync/init

POST

https://preview-deliver.kontent.ai/{environment_id}/sync/init

Request

Path parameters

environment_id

required · string

Identifies your environment.

Query parameters

system.type

string

system.collection

string

language

string

system.language

string

Request samples

TypeScript
C#
cURL

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { createDeliveryClient } from '@kontent-ai/delivery-sdk';

const deliveryClient = createDeliveryClient({
  environmentId: 'KONTENT_AI_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

Status (200)

Content synchronization was initialized.

items[]

array

List of delta updates for content items that changed since the last content synchronization.When you initialize content synchronization, the items array is always empty.

Hide child attributes

change_type

string

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

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.

data

object

The content item with metadata and individual elements.

Hide child attributes

system

required · object

The content item's system properties.

Hide child attributes

id

required · string · uuid

The content item's internal ID.

collection

required · string

The content item's collection codename. For projects without collections enabled, the value is default.

name

required · string

The content item's display name.

codename

required · string

The content item's codename. By default, generated from the item's display name.

language

required · string

The codename of the language that the content is in.For details on retrieving content in different languages, see Getting localized content.

type

required · string

The codename of the item's type.

sitemap_locations[]

required · array

Deprecated

A list of sitemap locations that the content item is in.

last_modified

required · string · date-time

ISO-8601

formatted date and time of the last change to user-content of the content item.

Moving content items through workflow doesn't affect the last_modified value.

workflow

string

The codename of the content item's current workflow. By default, generated from the workflow's display name.This property is not present for components.

workflow_step

string

The codename of the content item's current workflow step. By default, generated from the workflow step's display name.This property is not present for components.

<element_codename>

object

The item's elements with values for the specific language. The order of the element objects might not match the content element order in the UI.

Hide child attributes

required · nestedSchema

Any of:

Asset element

Custom element

Date and time element

Linked items element

Multiple choice element

Number element

Rich text element

Subpages element

Taxonomy element

Text element

URL slug element

Asset element

type

required · string

The element's type.

name

required · string · 1-50 chars

The element's display name.

value[]

required · array

Show child attributes

Example responses

200
400

{
  "items": []
}

Synchronize changes in content items

Deprecated

GET

https://deliver.kontent.ai/{environment_id}/sync

GET

https://preview-deliver.kontent.ai/{environment_id}/sync

Request

Path parameters

environment_id

required · string

Identifies your environment.

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.

Request samples

TypeScript
C#
cURL

// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { createDeliveryClient } from '@kontent-ai/delivery-sdk';

const deliveryClient = createDeliveryClient({
  environmentId: 'KONTENT_AI_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') {
    // Process a changed item
  } else if (item.changeType === 'deleted') {
    // Process a deleted item
  }
}

// Synchronize the next batch of changes
const nextResponse = await deliveryClient
  .syncChanges()
  .withContinuationToken(continuationToken)
  .toPromise();

Response

Status (200)

Delta updates of content items that changed since the previous sync

items[]

array · max. 500 items

List of delta updates for content items that changed since the last content synchronization.If there haven't been any changes, the items array is empty.

Hide child attributes

change_type

string

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

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.

data

object

The content item with metadata and individual elements.

Hide child attributes

system

required · object

The content item's system properties.

Hide child attributes

id

required · string · uuid

The content item's internal ID.

collection

required · string

The content item's collection codename. For projects without collections enabled, the value is default.

name

required · string

The content item's display name.

codename

required · string

The content item's codename. By default, generated from the item's display name.

language

required · string

The codename of the language that the content is in.For details on retrieving content in different languages, see Getting localized content.

type

required · string

The codename of the item's type.

sitemap_locations[]

required · array

Deprecated

A list of sitemap locations that the content item is in.

last_modified

required · string · date-time

ISO-8601

formatted date and time of the last change to user-content of the content item.

Moving content items through workflow doesn't affect the last_modified value.

workflow

string

The codename of the content item's current workflow. By default, generated from the workflow's display name.This property is not present for components.

workflow_step

string

The codename of the content item's current workflow step. By default, generated from the workflow step's display name.This property is not present for components.

<element_codename>

object

The item's elements with values for the specific language. The order of the element objects might not match the content element order in the UI.

Hide child attributes

required · nestedSchema

Any of:

Asset element

Custom element

Date and time element

Linked items element

Multiple choice element

Number element

Rich text element

Subpages element

Taxonomy element

Text element

URL slug element

Asset element

type

required · string

The element's type.

name

required · string · 1-50 chars

The element's display name.

value[]

required · array

Show child attributes

Example responses

200
400

{
  "items": [
    {
      "change_type": "changed_item",
      "timestamp": "2023-04-12T13:03:06.1310204Z",
      "data": {
        "system": {
          "id": "335d17ac-b6ba-4c6a-ae31-23c1193215cb",
          "collection": "default",
          "name": "Hello World",
          "codename": "hello_world",
          "language": "en-US",
          "type": "article",
          "sitemap_locations": [],
          "last_modified": "2019-03-27T13:21:11.38Z",
          "workflow": "default",
          "workflow_step": "published"
        },
        "elements": {
          "title": {
            "type": "text",
            "name": "Title",
            "value": "Hello World"
          }
        }
      }
    },
    {
      "change_type": "deleted_item",
      "timestamp": "2023-04-12T13:06:06.4210204Z",
      "data": {
        "system": {
          "id": "363d17ac-b6ba-4c6a-ae53-27c1172515cb",
          "collection": "default",
          "name": "Goodbye World",
          "codename": "bye_world",
          "language": "en-US",
          "type": "article",
          "sitemap_locations": [],
          "last_modified": "2019-03-27T13:21:11.38Z",
          "workflow": "default",
          "workflow_step": "published"
        },
        "elements": {
          "title": {
            "type": "text",
            "name": "Title",
            "value": "Goodbye World"
          }
        }
      }
    }
  ]
}