openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts Entries API
  description: The Contentstack Analytics API provides access to usage and performance metrics for CMS, Launch, and Automate products within a Contentstack organization. Developers can retrieve analytics data programmatically to build custom dashboards, monitor content delivery performance, and track platform usage against plan limits. The API returns structured data suitable for aggregation with external analytics and business intelligence tools. Access is restricted to organization Owners and Admins. Requests use async job-based processing where initial POST calls queue the job and a subsequent GET call retrieves the results.
  version: v2
  contact:
    name: Contentstack Support
    url: https://www.contentstack.com/contact
  termsOfService: https://www.contentstack.com/legal/terms-of-service
servers:
- url: https://api.contentstack.io
  description: AWS North America Production Server
- url: https://eu-api.contentstack.com
  description: AWS Europe Production Server
- url: https://au-api.contentstack.com
  description: AWS Australia Production Server
security:
- bearerAuth: []
- authtokenAuth: []
tags:
- name: Entries
  description: Entries are instances of content types that hold the actual content data. They can be filtered, sorted, paginated, and localized.
paths:
  /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'
    post:
      operationId: createEntry
      summary: Create an entry
      description: Creates a new entry for the specified content type. The entry data must conform to the content type schema. Newly created entries are in draft state and must be published separately.
      tags:
      - Entries
      parameters:
      - $ref: '#/components/parameters/StackApiKey'
      - $ref: '#/components/parameters/AuthToken'
      - $ref: '#/components/parameters/ContentTypeUid'
      - $ref: '#/components/parameters/Locale_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEntryRequest'
      responses:
        '201':
          description: The newly created entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entry_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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'
    put:
      operationId: updateEntry
      summary: Update an entry
      description: Updates the field values of an existing entry. Only the fields included in the request body are updated; other fields retain their current values.
      tags:
      - Entries
      parameters:
      - $ref: '#/components/parameters/StackApiKey'
      - $ref: '#/components/parameters/AuthToken'
      - $ref: '#/components/parameters/ContentTypeUid'
      - $ref: '#/components/parameters/EntryUid'
      - $ref: '#/components/parameters/Locale_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEntryRequest'
      responses:
        '200':
          description: The updated entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Entry_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteEntry
      summary: Delete an entry
      description: Permanently deletes an entry from the stack. Published entries must be unpublished before deletion. This action cannot be undone.
      tags:
      - Entries
      parameters:
      - $ref: '#/components/parameters/StackApiKey'
      - $ref: '#/components/parameters/AuthToken'
      - $ref: '#/components/parameters/ContentTypeUid'
      - $ref: '#/components/parameters/EntryUid'
      responses:
        '200':
          description: Entry deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /content_types/{content_type_uid}/entries/{entry_uid}/publish:
    post:
      operationId: publishEntry
      summary: Publish an entry
      description: Publishes an entry to one or more environments and locales. Publishing makes the entry available via the Content Delivery API for the specified environments.
      tags:
      - Entries
      parameters:
      - $ref: '#/components/parameters/StackApiKey'
      - $ref: '#/components/parameters/AuthToken'
      - $ref: '#/components/parameters/ContentTypeUid'
      - $ref: '#/components/parameters/EntryUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishRequest'
      responses:
        '200':
          description: Entry published successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /content_types/{content_type_uid}/entries/{entry_uid}/unpublish:
    post:
      operationId: unpublishEntry
      summary: Unpublish an entry
      description: Removes an entry from one or more environments, making it unavailable via the Content Delivery API for the specified environments.
      tags:
      - Entries
      parameters:
      - $ref: '#/components/parameters/StackApiKey'
      - $ref: '#/components/parameters/AuthToken'
      - $ref: '#/components/parameters/ContentTypeUid'
      - $ref: '#/components/parameters/EntryUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishRequest'
      responses:
        '200':
          description: Entry unpublished successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    AuthToken:
      name: authtoken
      in: header
      required: false
      description: User session token for authentication. Required if not using management token.
      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
    ContentTypeUid:
      name: content_type_uid
      in: path
      required: true
      description: The unique identifier (UID) of the content type.
      schema:
        type: string
    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
    Skip:
      name: skip
      in: query
      description: Number of entries to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    Locale_2:
      name: locale
      in: query
      description: The locale code for localized content operations.
      schema:
        type: string
        example: en-us
    AccessToken:
      name: access_token
      in: header
      required: true
      description: The delivery token for the stack environment.
      schema:
        type: string
    ApiKey:
      name: api_key
      in: header
      required: true
      description: The API key for the Contentstack stack.
      schema:
        type: string
    StackApiKey:
      name: api_key
      in: header
      required: true
      description: The API key identifying 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
  schemas:
    UpdateEntryRequest:
      type: object
      description: Parameters for updating an entry.
      required:
      - entry
      properties:
        entry:
          type: object
          description: Updated field values for the entry.
    PublishRequest:
      type: object
      description: Parameters for publishing or unpublishing an entry or asset.
      properties:
        entry:
          type: object
          description: Publish configuration.
          properties:
            environments:
              type: array
              description: List of environment names to publish to.
              items:
                type: string
            locales:
              type: array
              description: List of locale codes to publish.
              items:
                type: string
    CreateEntryRequest:
      type: object
      description: Parameters for creating a new entry.
      required:
      - entry
      properties:
        entry:
          type: object
          description: Entry field values conforming to the content type schema.
    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.
    Entry_2:
      type: object
      description: A content entry with field values and system metadata.
      properties:
        uid:
          type: string
          description: Unique identifier of the entry.
        title:
          type: string
          description: Title of the entry.
        locale:
          type: string
          description: Locale code of the entry.
        _version:
          type: integer
          description: Version number 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.
    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.
    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.
    Error_2:
      type: object
      description: Standard error response.
      properties:
        error_message:
          type: string
          description: Human-readable description of the error.
        error_code:
          type: integer
          description: Numeric error code.
        errors:
          type: object
          description: Field-level validation errors.
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is malformed or contains invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token (M2M) with analytics access.
    authtokenAuth:
      type: apiKey
      in: header
      name: authtoken
      description: Contentstack user authtoken. Only organization Owners and Admins can access analytics.
externalDocs:
  description: Contentstack Analytics API Documentation
  url: https://www.contentstack.com/docs/developers/apis/analytics-api