contentstack Entry Variants API

openapi: 3.2.0
info:
  title: Contentstack Content Delivery Entry Variants 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
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
security:
- apiKey: []
  deliveryToken: []
tags:
- name: Entry Variants
  description: Entry variants are customized versions of an entry created for personalization or A/B testing purposes.
paths:
  /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'
components:
  parameters:
    VariantUid:
      name: variant_uid
      in: path
      required: true
      description: The unique identifier (UID) of the entry variant.
      schema:
        type: string
    ApiKey:
      name: api_key
      in: header
      required: true
      description: The API key for the Contentstack stack.
      schema:
        type: string
    EntryUid:
      name: entry_uid
      in: path
      required: true
      description: The unique identifier (UID) of the entry.
      schema:
        type: string
    ContentTypeUid:
      name: content_type_uid
      in: path
      required: true
      description: The unique identifier (UID) of the content type.
      schema:
        type: string
    AccessToken:
      name: access_token
      in: header
      required: true
      description: The delivery token for the stack environment.
      schema:
        type: string
  schemas:
    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.
    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.
  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'
  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.
externalDocs:
  description: Contentstack Content Delivery API Documentation
  url: https://www.contentstack.com/docs/developers/apis/content-delivery-api