openapi: 3.1.0 info: title: Contentstack Content Delivery API description: >- The Contentstack Content Delivery API (CDA) allows developers to retrieve published content from their Contentstack stacks and deliver it to web or mobile applications. It supports fetching entries, assets, content types, and global fields through REST endpoints using stack API keys and delivery tokens for authentication. The API is read-only and optimized for high-performance content retrieval at scale. It supports filtering, sorting, pagination, localization, and synchronization, making it suitable for building localized, multi-channel digital experiences. version: 'v3' contact: name: Contentstack Support url: https://www.contentstack.com/contact termsOfService: https://www.contentstack.com/legal/terms-of-service externalDocs: description: Contentstack Content Delivery API Documentation url: https://www.contentstack.com/docs/developers/apis/content-delivery-api servers: - url: https://cdn.contentstack.io/v3 description: AWS North America Production Server - url: https://eu-cdn.contentstack.com/v3 description: AWS Europe Production Server - url: https://au-cdn.contentstack.com/v3 description: AWS Australia Production Server tags: - name: Assets description: >- Assets are media files such as images, videos, and documents stored in the Contentstack asset library. - name: Content Types description: >- Content types define the structure of content entries in a Contentstack stack. They specify the fields and their data types that entries must conform to. - name: Entries description: >- Entries are instances of content types that hold the actual content data. They can be filtered, sorted, paginated, and localized. - name: Entry Variants description: >- Entry variants are customized versions of an entry created for personalization or A/B testing purposes. - name: Global Fields description: >- Global fields are reusable field groups that can be referenced across multiple content types within a Contentstack stack. - name: Synchronization description: >- The synchronization endpoints allow developers to sync published content incrementally, enabling efficient local caching and offline-first patterns. security: - apiKey: [] deliveryToken: [] paths: /content_types: get: operationId: getAllContentTypes summary: Get all content types description: >- Retrieves comprehensive information of all content types available in a stack. Supports include_count parameter to return the total count of content types. tags: - Content Types parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/AccessToken' - name: include_count in: query description: Set to true to include the total count of content types in the response. schema: type: boolean responses: '200': description: A list of content types in the stack. content: application/json: schema: $ref: '#/components/schemas/ContentTypeList' '401': $ref: '#/components/responses/Unauthorized' /content_types/{content_type_uid}: get: operationId: getSingleContentType summary: Get a single content type description: >- Returns detailed information for a specific content type identified by its UID, including all field definitions and schema metadata. tags: - Content Types parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/AccessToken' - $ref: '#/components/parameters/ContentTypeUid' - name: version in: query description: Retrieve a specific version of the content type schema. schema: type: integer responses: '200': description: Details of the specified content type. content: application/json: schema: $ref: '#/components/schemas/ContentType' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /content_types/{content_type_uid}/entries: get: operationId: getAllEntries summary: Get all entries description: >- Fetches a list of all published entries for a particular content type. Supports filtering by query, localization, reference inclusion, pagination, sorting, and field selection. tags: - Entries parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/AccessToken' - $ref: '#/components/parameters/ContentTypeUid' - $ref: '#/components/parameters/Locale' - $ref: '#/components/parameters/Skip' - $ref: '#/components/parameters/Limit' - name: query in: query description: >- A JSON-encoded query object to filter entries. Supports MongoDB-style query operators for field matching and comparison. schema: type: string - name: include_count in: query description: Set to true to include the total count of matching entries. schema: type: boolean - name: include_content_type in: query description: Set to true to include the content type schema in the response. schema: type: boolean - name: include_reference in: query description: Set to true to include referenced entries inline in the response. schema: type: boolean - name: only in: query description: Comma-separated list of fields to include in the response. schema: type: string - name: except in: query description: Comma-separated list of fields to exclude from the response. schema: type: string - name: asc in: query description: Field name to sort results in ascending order. schema: type: string - name: desc in: query description: Field name to sort results in descending order. schema: type: string responses: '200': description: A list of published entries for the specified content type. content: application/json: schema: $ref: '#/components/schemas/EntryList' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /content_types/{content_type_uid}/entries/{entry_uid}: get: operationId: getSingleEntry summary: Get a single entry description: >- Retrieves a specific published entry identified by its UID within a given content type. Supports localization, reference inclusion, and field selection parameters. tags: - Entries parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/AccessToken' - $ref: '#/components/parameters/ContentTypeUid' - $ref: '#/components/parameters/EntryUid' - $ref: '#/components/parameters/Locale' - name: include_reference in: query description: Set to true to include referenced entries inline in the response. schema: type: boolean - name: version in: query description: Retrieve a specific published version of the entry. schema: type: integer responses: '200': description: The requested entry object. content: application/json: schema: $ref: '#/components/schemas/Entry' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /content_types/{content_type_uid}/entries/{entry_uid}/variants: get: operationId: getAllEntryVariants summary: Get all entry variants description: >- Retrieves all personalization variants of a specific entry, including their variant UIDs and customized field values. tags: - Entry Variants parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/AccessToken' - $ref: '#/components/parameters/ContentTypeUid' - $ref: '#/components/parameters/EntryUid' responses: '200': description: A list of variants for the specified entry. content: application/json: schema: $ref: '#/components/schemas/EntryVariantList' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /content_types/{content_type_uid}/entries/{entry_uid}/variants/{variant_uid}: get: operationId: getSingleEntryVariant summary: Get a single entry variant description: >- Retrieves a specific variant of an entry identified by the variant UID. Returns the customized field values for that variant. tags: - Entry Variants parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/AccessToken' - $ref: '#/components/parameters/ContentTypeUid' - $ref: '#/components/parameters/EntryUid' - $ref: '#/components/parameters/VariantUid' responses: '200': description: The requested entry variant object. content: application/json: schema: $ref: '#/components/schemas/EntryVariant' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /assets: get: operationId: getAllAssets summary: Get all assets description: >- Fetches a list of all published assets in the stack including images, videos, and documents. Supports pagination, filtering, and field selection. tags: - Assets parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/AccessToken' - $ref: '#/components/parameters/Skip' - $ref: '#/components/parameters/Limit' - name: include_count in: query description: Set to true to include the total count of assets in the response. schema: type: boolean responses: '200': description: A list of assets in the stack. content: application/json: schema: $ref: '#/components/schemas/AssetList' '401': $ref: '#/components/responses/Unauthorized' /assets/{asset_uid}: get: operationId: getSingleAsset summary: Get a single asset description: >- Retrieves a specific asset by its UID, returning all metadata including file URL, dimensions, file size, and content type. tags: - Assets parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/AccessToken' - $ref: '#/components/parameters/AssetUid' responses: '200': description: The requested asset object. content: application/json: schema: $ref: '#/components/schemas/Asset' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /global_fields: get: operationId: getAllGlobalFields summary: Get all global fields description: >- Fetches all reusable global field definitions available in the stack. Global fields can be embedded in content type schemas to create consistent field structures across multiple content types. tags: - Global Fields parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/AccessToken' responses: '200': description: A list of global fields defined in the stack. content: application/json: schema: $ref: '#/components/schemas/GlobalFieldList' '401': $ref: '#/components/responses/Unauthorized' /global_fields/{global_field_uid}: get: operationId: getSingleGlobalField summary: Get a single global field description: >- Returns the schema and metadata for a specific global field identified by its UID. tags: - Global Fields parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/AccessToken' - $ref: '#/components/parameters/GlobalFieldUid' responses: '200': description: The requested global field object. content: application/json: schema: $ref: '#/components/schemas/GlobalField' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /stacks/sync: get: operationId: syncContent summary: Sync content description: >- Initiates an initial sync or continues a paginated sync of all published entries and assets in the stack. Use init=true for the first sync to receive a sync token. Use the sync_token from subsequent responses to fetch only the changes since the last sync. tags: - Synchronization parameters: - $ref: '#/components/parameters/ApiKey' - $ref: '#/components/parameters/AccessToken' - name: init in: query description: Set to true to initiate the first sync and receive a sync token. schema: type: boolean - name: sync_token in: query description: >- The token received from a previous sync response. Use to fetch only changes since the last sync. schema: type: string - name: pagination_token in: query description: >- Token to retrieve the next page of results in a large sync response. schema: type: string - name: type in: query description: >- Filter sync results by content type. Options: entry_published, entry_unpublished, entry_deleted, asset_published, asset_unpublished, asset_deleted, content_type_deleted. schema: type: string enum: - entry_published - entry_unpublished - entry_deleted - asset_published - asset_unpublished - asset_deleted - content_type_deleted - name: content_type_uid in: query description: Filter sync results to a specific content type UID. schema: type: string - $ref: '#/components/parameters/Locale' responses: '200': description: Sync results with a sync_token or pagination_token for continuation. content: application/json: schema: $ref: '#/components/schemas/SyncResponse' '401': $ref: '#/components/responses/Unauthorized' components: securitySchemes: apiKey: type: apiKey in: header name: api_key description: The API key for the Contentstack stack. deliveryToken: type: apiKey in: header name: access_token description: The delivery token granting read access to the stack environment. parameters: ApiKey: name: api_key in: header required: true description: The API key for the Contentstack stack. schema: type: string AccessToken: name: access_token in: header required: true description: The delivery token for the stack environment. schema: type: string ContentTypeUid: name: content_type_uid in: path required: true description: The unique identifier (UID) of the content type. schema: type: string EntryUid: name: entry_uid in: path required: true description: The unique identifier (UID) of the entry. schema: type: string VariantUid: name: variant_uid in: path required: true description: The unique identifier (UID) of the entry variant. schema: type: string AssetUid: name: asset_uid in: path required: true description: The unique identifier (UID) of the asset. schema: type: string GlobalFieldUid: name: global_field_uid in: path required: true description: The unique identifier (UID) of the global field. schema: type: string Locale: name: locale in: query description: >- The locale code to retrieve localized content. Defaults to the default locale of the stack if not specified. schema: type: string example: en-us Skip: name: skip in: query description: Number of entries to skip for pagination. schema: type: integer minimum: 0 default: 0 Limit: name: limit in: query description: Maximum number of entries to return. Maximum allowed is 250. schema: type: integer minimum: 1 maximum: 250 default: 100 responses: Unauthorized: description: Authentication credentials are missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: ContentTypeList: type: object description: A paginated list of content types in the stack. properties: content_types: type: array description: Array of content type objects. items: $ref: '#/components/schemas/ContentType' count: type: integer description: Total count of content types when include_count is true. ContentType: type: object description: A content type definition including schema and metadata. properties: uid: type: string description: Unique identifier of the content type. title: type: string description: Display name of the content type. schema: type: array description: Array of field definitions for the content type. items: $ref: '#/components/schemas/Field' options: type: object description: Configuration options for the content type such as versioning and workflow settings. created_at: type: string format: date-time description: ISO 8601 timestamp when the content type was created. updated_at: type: string format: date-time description: ISO 8601 timestamp when the content type was last updated. Field: type: object description: A field definition within a content type schema. properties: uid: type: string description: Unique identifier of the field within the content type. data_type: type: string description: >- The data type of the field. Common values: text, number, boolean, date, file, link, json, reference, global_field, group, blocks. display_name: type: string description: Human-readable label for the field. mandatory: type: boolean description: Indicates whether the field is required for entry creation. unique: type: boolean description: Indicates whether field values must be unique across entries. EntryList: type: object description: A paginated list of published entries. properties: entries: type: array description: Array of entry objects. items: $ref: '#/components/schemas/Entry' count: type: integer description: Total count of matching entries when include_count is true. Entry: type: object description: A published content entry with all its field values. properties: uid: type: string description: Unique identifier of the entry. title: type: string description: The title of the entry. locale: type: string description: The locale code of the entry. created_at: type: string format: date-time description: ISO 8601 timestamp when the entry was created. updated_at: type: string format: date-time description: ISO 8601 timestamp when the entry was last updated. published_at: type: string format: date-time description: ISO 8601 timestamp when the entry was last published. EntryVariantList: type: object description: A list of personalization variants for an entry. properties: entries: type: array description: Array of entry variant objects. items: $ref: '#/components/schemas/EntryVariant' EntryVariant: type: object description: A personalization variant of a content entry. properties: uid: type: string description: Unique identifier of the entry variant. variant_uid: type: string description: The variant identifier linking this entry to a personalization variant. locale: type: string description: The locale code of the entry variant. AssetList: type: object description: A paginated list of assets in the stack. properties: assets: type: array description: Array of asset objects. items: $ref: '#/components/schemas/Asset' count: type: integer description: Total count of assets when include_count is true. Asset: type: object description: A media asset stored in the Contentstack asset library. properties: uid: type: string description: Unique identifier of the asset. title: type: string description: Display name of the asset. url: type: string format: uri description: CDN URL to access the asset file. filename: type: string description: Original file name of the uploaded asset. content_type: type: string description: MIME type of the asset file. file_size: type: string description: File size of the asset in bytes. created_at: type: string format: date-time description: ISO 8601 timestamp when the asset was created. updated_at: type: string format: date-time description: ISO 8601 timestamp when the asset was last updated. GlobalFieldList: type: object description: A list of global field definitions in the stack. properties: global_fields: type: array description: Array of global field objects. items: $ref: '#/components/schemas/GlobalField' GlobalField: type: object description: A reusable global field definition that can be embedded in content types. properties: uid: type: string description: Unique identifier of the global field. title: type: string description: Display name of the global field. schema: type: array description: Array of field definitions within the global field group. items: $ref: '#/components/schemas/Field' created_at: type: string format: date-time description: ISO 8601 timestamp when the global field was created. updated_at: type: string format: date-time description: ISO 8601 timestamp when the global field was last updated. SyncResponse: type: object description: >- The response from a content sync operation, containing the synced items and tokens for subsequent sync requests. properties: items: type: array description: Array of sync item objects representing content changes. items: $ref: '#/components/schemas/SyncItem' paginationToken: type: string description: >- Token to retrieve the next page of sync results. Present only when more pages are available. syncToken: type: string description: >- Token representing the current sync state. Use this in subsequent sync requests to receive only new changes. total_count: type: integer description: Total number of items in the sync response. limit: type: integer description: Maximum items returned per page. skip: type: integer description: Number of items skipped in this response. SyncItem: type: object description: A single item in a sync response representing a content change event. properties: type: type: string description: >- The type of sync event. Possible values: entry_published, entry_unpublished, entry_deleted, asset_published, asset_unpublished, asset_deleted, content_type_deleted. enum: - entry_published - entry_unpublished - entry_deleted - asset_published - asset_unpublished - asset_deleted - content_type_deleted data: type: object description: The content data associated with this sync event. content_type_uid: type: string description: The UID of the content type for entry-related events. locale: type: string description: The locale of the content for locale-specific events. Error: type: object description: Standard error response returned by the API. properties: error_message: type: string description: Human-readable description of the error. error_code: type: integer description: Numeric code identifying the error type. errors: type: object description: Field-level validation errors when applicable.