• Cheat sheets
  • Documentation
  • API reference
  • Product updates
  • Sign in
Kontent.ai Learn
  • Try Kontent.ai
  • Plan
  • Set up
  • Model
  • Develop
  • Create
Sync API v2
API Reference
    • About Sync API
    • Why use Sync API?
    • Authentication
    • Postman collection
    • SDKs
    • API limitations
    • Guidelines on handling changes
      • Introduction
      • Content item delta object
        Schema
      • Content type delta object
        Schema
      • Language delta object
        Schema
      • Taxonomy group delta object
        Schema
      • Initialize content synchronization
        POST
      • Synchronize changes
        GET

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 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:
  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.
Accepted values:
changed, deleted
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.
data
required · object · read-only
The affected content item's metadata.
JSON
{
  "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.
Accepted values:
changed, deleted
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.
data
required · object
The affected content type's metadata.
JSON
{
  "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.
Accepted values:
changed, deleted
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.
data
required · object · read-only
The metadata of the affected language.
JSON
{
  "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.
Accepted values:
changed, deleted
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.
data
required · object
The affected taxonomy group's metadata.
JSON
{
  "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

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.
POST
https://deliver.kontent.ai/v2/{environment_id}/sync/init
POST
https://preview-deliver.kontent.ai/v2/{environment_id}/sync/init

Request

Path parameters

environment_id
required · string
Identifies your environment.

Request samples

TypeScript
C#
cURL
// Tip: Find more about JS SDK at https://github.com/kontent-ai/sync-sdk-js
import { getSyncClient } from '@kontent-ai/sync-sdk-js';
import { writeFile } from 'fs/promises';

// Create a client with public API access
const client = getSyncClient('your-environment-id').publicApi().create();

// Initialize synchronization
const { success, response, error } = await client.init().toPromise();

if (!success) {
  // Handle initialization error
  console.error('Failed to initialize sync:', error.message);
  return;
}

// Get the continuation token for future sync operations
const continuationToken = response.meta.continuationToken;

// Store the last continuation token in persistent storage (fs, db, etc.) for future sync operations
await writeFile('syncApiToken', continuationToken, 'utf8');

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.
types[]
array
List of delta updates for content types that changed since the last content synchronization.When you initialize content synchronization, the types array is always empty.
languages[]
array
List of delta updates for languages that changed since the last content synchronization.When you initialize content synchronization, the languages array is always empty.
taxonomies[]
array
List of delta updates for taxonomy groups that changed since the last content synchronization.When you initialize content synchronization, the taxonomies array is always empty.

Example responses

200
{
  "items": [],
  "types": [],
  "languages": [],
  "taxonomies": []
}

Synchronize changes

Retrieve a list of delta updates to recently changed entities. You can follow the rest of the steps on how to sync changes.
GET
https://deliver.kontent.ai/v2/{environment_id}/sync
GET
https://preview-deliver.kontent.ai/v2/{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 SDK at https://github.com/kontent-ai/sync-sdk-js
import { getSyncClient } from '@kontent-ai/sync-sdk-js';
import { writeFile } from 'fs/promises';

// Create a client with public API access
const client = getSyncClient('your-environment-id').publicApi().create();

// Sync changes using the continuation token
const { success, responses, lastContinuationToken, error } = await client
  .sync('stored-continuation-token')
  .toAllPromise();

if (!success) {
  // Handle sync error
  console.error('Failed to sync changes:', error.message);
  return;
}

// Process all responses
for (const response of responses) {
  const { items, types, languages, taxonomies } = response.payload;
  // ... handle the changes
}

// Store the last continuation token in persistent storage (fs, db, etc.) for future sync operations
await writeFile('syncApiToken', lastContinuationToken, 'utf8');

Response

Status (200)
Delta updates of entities that changed since previous sync.
items[]
required · array · max. 100 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.
types[]
required · array · max. 100 items
List of delta updates for content types that changed since the last content synchronization.If there haven't been any changes, the types array is empty.
languages[]
required · array · max. 100 items
List of delta updates for languages that changed since the last content synchronization.If there haven’t been any changes, the languages array is empty.
taxonomies[]
required · array · max. 100 items
List of delta updates for taxonomy groups that changed since the last content synchronization.If there haven’t been any changes, the taxonomies array is empty.

Example responses

200
400
{
  "items": [
    {
      "change_type": "changed",
      "timestamp": "2025-05-28T05:33:58.6348403Z",
      "data": {
        "system": {
          "id": "79eab20c-f4b6-4a93-bf01-17096cbfa765",
          "name": "Test content item",
          "codename": "content_item",
          "language": "default",
          "type": "child",
          "collection": "default",
          "last_modified": "2025-05-27T10:20:07.0340165Z",
          "workflow": "default",
          "workflow_step": "published"
        }
      }
    },
    {
      "change_type": "deleted",
      "timestamp": "2025-05-28T09:11:42.3361261Z",
      "data": {
        "system": {
          "id": "79807741-234f-47c4-aec0-102a97c9779b",
          "name": "Child",
          "codename": "child",
          "language": "default",
          "type": "child",
          "collection": "default",
          "last_modified": "2025-03-04T10:17:19.8445811Z",
          "workflow": "default",
          "workflow_step": "published"
        }
      }
    }
  ],
  "types": [
    {
      "change_type": "changed",
      "timestamp": "2025-05-28T09:10:46.2792473Z",
      "data": {
        "system": {
          "id": "ebf65f57-a572-4586-9c85-03022db35bcc",
          "name": "Type",
          "codename": "type",
          "last_modified": "2025-05-28T09:10:43.9856679Z"
        }
      }
    }
  ],
  "taxonomies": [
    {
      "change_type": "changed",
      "timestamp": "2025-05-28T09:10:58.9337234Z",
      "data": {
        "system": {
          "id": "b34b9c8c-c80f-4516-9077-b17b69d9e381",
          "name": "Taxonomy",
          "codename": "taxonomy",
          "last_modified": "2025-05-28T09:10:58.0433607Z"
        }
      }
    }
  ],
  "languages": [
    {
      "change_type": "deleted",
      "timestamp": "2025-05-28T09:11:28.7212524Z",
      "data": {
        "system": {
          "id": "bf6678d8-b856-4a33-8b52-36401ed7ac59",
          "name": "English",
          "codename": "english"
        }
      }
    }
  ]
}
Copyright © 2026 Kontent.ai. All rights reserved.
  • Web
  • Privacy policy
  • Cookies policy
  • Consent settings
  • Security
  • GDPR