Synchronization

The Sync API allows you to keep a local copy of all content in a space up-to-date via delta updates, or only the content that has changed.

Syncing specific content

By default a sync request response includes all resource types including assets, entries of all content types and deleted resources.

To sync specific content you can specify a type parameter for the initial sync:

Initial synchronization

A client syncs content by using the sync endpoint. A single sync consists of one or more pages, each a separate request and response.

The first time a client synchronizes content it sends a request to the sync endpoint with the URI query parameter initial set to true.

You should only sync with initial=true for the initial sync when a client has no existing content. This transfers all content from a space, but does not contain content deleted from fields or deleted assets and content entries.

The limit parameter sets the page size for the number of retrieved entries. The limit is useful when you have very large content entries and reach the maximum response size limit. This limit is then encoded in the synchronization token and used for all following synchronizations.

Sync contains content from all environments.

Use the Get synced content endpoint, see example:

/spaces/yadj1kx9rmg0/sync?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&initial=true&type=Deletion&limit=42

Initial synchronization of entries of a specific content type

For entries, you can also specify a content_type parameter. When specifying content_type you must specify type as Entry (meaning there will be no deletions). You can only specify the type and content_type parameter at the initial sync along with the initial parameter. Any subsequent syncs will only include the types you have specified. If you want to sync entries by content type you should separately subscribe to a Deletion or DeletedEntry sync to be notified when entries are deleted.

Use the Get synced content endpoint, see example:

/spaces/yadj1kx9rmg0/sync?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&initial=true&type=Entry&content_type=2PqfXUJwE8qSYKuM0U6w8M&limit=42

Pagination and subsequent syncs

Synchronization responses contain either a nextPageUrl or nextSyncUrl attribute. If there is more content for the current sync, nextPageUrl will contain an URL with a sync_token which will retrieve the next page. This continues until you have retrieved all content.

At this point, the response will contain a nextSyncUrl which you use to make requests in the future and retrieve delta updates between the current content on Contentful and what you retrieved with your last sync request. Upon completion, you will receive a new nextSyncUrl which you can again use for future updates.

If a client loses the nextSyncUrl, the client should delete its local content and perform an initial synchronization again.

NOTE: The initial query with sync_token will persist across subsequent syncs.

Use the Get synced content endpoint, see example:

/spaces/yadj1kx9rmg0/sync?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&sync_token=w7Ese3kdwpMbMhhgw7QAUsKiw6bCi09CwpFYwpwywqVYw6DDh8OawrTDpWvCgMOhw6jCuAhxWX_CocOPwowhcsOzeEJSbcOvwrfDlCjDr8O1YzLDvi9FOTXCmsOqT8OFcHPDuFDCqyMMTsKNw7rDmsOqKcOnw7FCwpIfNMOcFMOxFnHCoCzDpAjCucOdwpwfw4YTK8Kpw6zCtDrChVQlNsO2ZybDnw

sync_token is an opaque token which is used to identify your previous sync.

Structure of deleted entities

For deletions, objects of the types DeletedAsset and DeletedEntry are sent. Those do not contain full assets or entries.

Query deleted entries

Use the Get synced content endpoint, see example:

/spaces/yadj1kx9rmg0/sync?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&sync_token=wonDrcKnRgcSOF4-wrDCgcKefWzCgsOxDCvDsMO3MMO6wpLDs2bDjH4kwo48NWjDuMOqwqnDn0Ztwq7CpMKdwofDjXknwrZcXmsDw57Dj8O3w5bChCAVE8OVOsK9KRbColwrY8OQw6QBC8Kqw47Cq3jDnsO8TUU6wp3DicK8w6zCr8OTJxI4OVfCqw3Dr8ObHg

The response will look like:

{
  "sys": {
    "type": "Array"
  },
  "items": [
    {
      "space": {
        "sys": {
          "type": "Link",
          "linkType": "Space",
          "id": "yadj1kx9rmg0"
        }
      },
      "id": "5JMlyOmxS8gGkAwUmksigY",
      "type": "DeletedEntry",
      "createdAt": "2018-01-10T12:24:21.044Z",
      "updatedAt": "2018-01-10T12:24:21.044Z",
      "deletedAt": "2018-01-10T12:24:21.044Z",
      "revision": "1"
    }
  ],
  "nextSyncUrl": "https://cdn.contentful.com/spaces/yadj1kx9rmg0/sync?sync_token=wonDrcKnRgcSOF4-wrDCgcKefWzCgsOxDCvDsMO3MMO6wpLDs2bDjH4kwo48NWjDuMOqwqnDn0Ztwq7CpMKdwofDjXknwrZcXmsDw57Dj8O3w5bChCAVE8OVOsK9KRbColwrY8OQw6QBC8Kqw47Cq3jDnsO8TUU6wp3DicK8w6zCr8OTJxI4OVfCqw3Dr8ObHg"
}

Query deleted assets

Use the Get synced content endpoint, see example:

/spaces/yadj1kx9rmg0/sync?access_token=fdb4e7a3102747a02ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe&sync_token=wonDrcKnRgcSOF4-wrDCgcKefWzCgsOxDCvDsMO3MMO6wpLDs2bDjH4kwo48NWjDuMOqwqnDn0Ztwq7CpMKdwofDjXknwrZcXmsDw57Dj8O3w5bChCAVE8OVOsK9KRbColwrY8OQw6QBC8Kqw47Cq3jDnsO8TUU6wp3DicK8w6zCr8OTJxI4OVfCqw3Dr8ObHg

The response will look like:

{
  "sys": {
    "type": "Array"
  },
  "items": [
    {
      "space": {
        "sys": {
          "type": "Link",
          "linkType": "Space",
          "id": "yadj1kx9rmg0"
        }
      },
      "id": "5BfQVRz3QkAgcMqaCGa2my",
      "type": "DeletedAsset",
      "createdAt": "2018-01-10T12:30:27.120Z",
      "updatedAt": "2018-01-10T12:30:27.120Z",
      "deletedAt": "2018-01-10T12:30:27.120Z",
      "revision": "1"
    }
  ],
  "nextSyncUrl": "https://cdn.contentful.com/spaces/yadj1kx9rmg0/sync?sync_token=wonDrcKnRgcSOF4-wrDCgcKefWzCgsOxDCvDsMO3MMO6wpLDs2bDjH4kwo48NWjDuMOqwqnDn0Ztwq7CpMKdwofDjXknwrZcXhrDtMKiw6TCmm_DlxTDjizDqkvCusOpwolsw67DmVTDnMKWFMOGw65kwoEvwrjDoMK_axLCkMKKw6nCosOqwrNCw6M6wpp0XlHDgsKHaQ"
}