Subchapter 3.6
references/content-delivery/sync.mdMarkdown4 KBView on GitHub
The Sync API enables incremental content synchronization. Instead of fetching all content repeatedly, sync once initially, then fetch only changes since the last sync.
Fetch all content for the first time:
curl "https://cdn.contentful.com/spaces/{space_id}/environments/master/sync?initial=true" \
-H "Authorization: Bearer {cda_token}"Response:
{
"sys": { "type": "Array" },
"items": [
{
"sys": { "type": "Entry", "id": "entry-1", "contentType": { "sys": { "id": "blogPost" } }, ... },
"fields": { "title": "Hello World" }
},
{
"sys": { "type": "Asset", "id": "asset-1", ... },
"fields": { "title": "Hero Image", "file": { ... } }
},
{
"sys": { "type": "DeletedEntry", "id": "entry-2", ... }
},
{
"sys": { "type": "DeletedAsset", "id": "asset-2", ... }
}
],
"nextSyncUrl": "https://cdn.contentful.com/spaces/{space_id}/environments/master/sync?sync_token=next-token-here"
}Store the nextSyncUrl (or extract sync_token from it) for subsequent syncs.
Fetch only changes since the last sync:
curl "https://cdn.contentful.com/spaces/{space_id}/environments/master/sync?sync_token={token}" \
-H "Authorization: Bearer {cda_token}"Response contains only entries/assets that were created, updated, or deleted since the last sync.
{
"sys": { "type": "Array" },
"items": [
{
"sys": { "type": "Entry", "id": "entry-3", ... },
"fields": { "title": "New Post" }
},
{
"sys": { "type": "DeletedEntry", "id": "entry-1", ... }
}
],
"nextSyncUrl": "https://cdn.contentful.com/spaces/{space_id}/environments/master/sync?sync_token=newer-token"
}If there are too many results for a single response, the response includes nextPageUrl instead of (or in addition to) nextSyncUrl:
{
"items": [ ... ],
"nextPageUrl": "https://cdn.contentful.com/spaces/{space_id}/environments/master/sync?sync_token=page-2-token"
}Follow nextPageUrl to get the next page. When nextPageUrl is absent and nextSyncUrl is present, you’ve reached the last page. Store nextSyncUrl for the next sync cycle.
Loop:
1. Call sync URL
2. Process items
3. If nextPageUrl exists → go to step 1 with nextPageUrl
4. If nextSyncUrl exists → done, store nextSyncUrl for next syncItems in the sync response have these sys.type values:
| Type | Description |
|---|---|
Entry | New or updated entry (full entry with fields) |
Asset | New or updated asset (full asset with fields) |
DeletedEntry | Entry was deleted (only sys metadata, no fields) |
DeletedAsset | Asset was deleted (only sys metadata, no fields) |
Limit the initial sync to specific content:
# Only entries
...?initial=true&type=Entry
# Only assets
...?initial=true&type=Asset
# Only deletions (both entries and assets)
...?initial=true&type=Deletion# Only entries of a specific content type
...?initial=true&type=Entry&content_type=blogPostNote: Filtered sync tokens are separate — a token from a filtered sync can only be used for subsequent syncs with the same filter.
locale=*)include — links are not resolved. You get link stubs and must resolve manuallyselectnextSyncUrl or sync_token between runsnextPageUrl before storing nextSyncUrl