openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts Assets 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: Assets
  description: Assets are media files such as images, videos, and documents stored in the Contentstack asset library.
paths:
  /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'
    post:
      operationId: uploadAsset
      summary: Upload an asset
      description: Uploads a new asset file to the stack. Supports multipart form data for the file upload along with metadata such as title, description, and tags.
      tags:
      - Assets
      parameters:
      - $ref: '#/components/parameters/StackApiKey'
      - $ref: '#/components/parameters/AuthToken'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                asset[upload]:
                  type: string
                  format: binary
                  description: The asset file to upload.
                asset[title]:
                  type: string
                  description: Display title for the asset.
                asset[description]:
                  type: string
                  description: Description of the asset content.
      responses:
        '201':
          description: The newly uploaded asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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'
components:
  parameters:
    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
    AccessToken:
      name: access_token
      in: header
      required: true
      description: The delivery token for the stack environment.
      schema:
        type: string
    AssetUid:
      name: asset_uid
      in: path
      required: true
      description: The unique identifier (UID) of the asset.
      schema:
        type: string
    AuthToken:
      name: authtoken
      in: header
      required: false
      description: User session token for authentication. Required if not using management token.
      schema:
        type: string
    ApiKey:
      name: api_key
      in: header
      required: true
      description: The API key for the Contentstack stack.
      schema:
        type: string
    Skip:
      name: skip
      in: query
      description: Number of entries to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
    StackApiKey:
      name: api_key
      in: header
      required: true
      description: The API key identifying the Contentstack stack.
      schema:
        type: string
  schemas:
    Asset_2:
      type: object
      description: A media asset stored in the stack.
      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: URL to access the asset file.
        filename:
          type: string
          description: Original file name of the uploaded file.
        content_type:
          type: string
          description: MIME type of the asset.
        file_size:
          type: string
          description: File size in bytes.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the asset was created.
    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.
    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.
    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'
  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