contentstack Content Types API

openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts Content Types 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: 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.
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'
    post:
      operationId: createContentType
      summary: Create a content type
      description: Creates a new content type in the stack with a defined schema of fields. The schema determines the structure of all entries created from this content type.
      tags:
      - Content Types
      parameters:
      - $ref: '#/components/parameters/StackApiKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContentTypeRequest'
      responses:
        '201':
          description: The newly created content type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentType_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
    put:
      operationId: updateContentType
      summary: Update a content type
      description: Updates the schema and options of an existing content type. Changes to the schema may affect existing entries that use this content type.
      tags:
      - Content Types
      parameters:
      - $ref: '#/components/parameters/StackApiKey'
      - $ref: '#/components/parameters/ContentTypeUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContentTypeRequest'
      responses:
        '200':
          description: The updated content type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentType_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteContentType
      summary: Delete a content type
      description: Permanently deletes a content type from the stack. All entries of this content type must be deleted before the content type can be removed.
      tags:
      - Content Types
      parameters:
      - $ref: '#/components/parameters/StackApiKey'
      - $ref: '#/components/parameters/ContentTypeUid'
      responses:
        '200':
          description: Content type deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ContentType_2:
      type: object
      description: A content type definition with schema and configuration.
      properties:
        uid:
          type: string
          description: Unique identifier of the content type.
        title:
          type: string
          description: Display name of the content type.
        description:
          type: string
          description: Description of the content type's purpose.
        schema:
          type: array
          description: Array of field definitions.
          items:
            $ref: '#/components/schemas/Field_2'
        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.
    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.
    CreateContentTypeRequest:
      type: object
      description: Parameters for creating or updating a content type.
      required:
      - content_type
      properties:
        content_type:
          type: object
          required:
          - uid
          - title
          - schema
          properties:
            uid:
              type: string
              description: Unique identifier for the content type.
            title:
              type: string
              description: Display name of the content type.
            schema:
              type: array
              description: Array of field definitions.
              items:
                $ref: '#/components/schemas/Field_2'
            options:
              type: object
              description: Configuration options for the content type.
    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.
    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.
    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.
    Field_2:
      type: object
      description: A field definition within a content type schema.
      properties:
        uid:
          type: string
          description: Unique identifier of the field.
        data_type:
          type: string
          description: Data type of the field (e.g., text, number, boolean, date, file, reference).
        display_name:
          type: string
          description: Human-readable label for the field.
        mandatory:
          type: boolean
          description: Indicates whether the field is required.
        unique:
          type: boolean
          description: Indicates whether field values must be unique.
    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'
    BadRequest:
      description: The request is malformed or contains invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    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
    ContentTypeUid:
      name: content_type_uid
      in: path
      required: true
      description: The unique identifier (UID) of the content type.
      schema:
        type: string
    StackApiKey:
      name: api_key
      in: header
      required: true
      description: The API key identifying the Contentstack stack.
      schema:
        type: string
  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