openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts Deployments 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: Deployments
  description: Deployments represent individual build and publish operations to a Launch environment. Each deployment has associated build logs, server logs, and status tracking.
paths:
  /projects/{project_uid}/environments/{env_uid}/deployments:
    get:
      operationId: getAllDeployments
      summary: Get all deployments
      description: Retrieves all deployments for a specific environment, showing deployment history with status, creation times, and build metadata.
      tags:
      - Deployments
      parameters:
      - $ref: '#/components/parameters/ProjectUid'
      - $ref: '#/components/parameters/EnvUid'
      responses:
        '200':
          description: A list of deployments for the environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDeployment
      summary: Create a deployment
      description: Triggers a new deployment to the specified environment. Requires a previously uploaded build artifact referenced by its upload URL. The deployment process builds and publishes the application to the environment's CDN infrastructure.
      tags:
      - Deployments
      parameters:
      - $ref: '#/components/parameters/ProjectUid'
      - $ref: '#/components/parameters/EnvUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeploymentRequest'
      responses:
        '201':
          description: Deployment created and queued for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{project_uid}/environments/{env_uid}/deployments/{deploy_uid}:
    get:
      operationId: getDeployment
      summary: Get a deployment
      description: Retrieves the full details of a specific deployment including its status, build configuration, and completion information.
      tags:
      - Deployments
      parameters:
      - $ref: '#/components/parameters/ProjectUid'
      - $ref: '#/components/parameters/EnvUid'
      - $ref: '#/components/parameters/DeployUid'
      responses:
        '200':
          description: The requested deployment details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deployment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_uid}/environments/{env_uid}/deployments/{deploy_uid}/logs:
    get:
      operationId: getDeploymentLogs
      summary: Get deployment logs
      description: Retrieves the build and deployment logs for a specific deployment, useful for debugging failed deployments and monitoring build progress.
      tags:
      - Deployments
      parameters:
      - $ref: '#/components/parameters/ProjectUid'
      - $ref: '#/components/parameters/EnvUid'
      - $ref: '#/components/parameters/DeployUid'
      responses:
        '200':
          description: The deployment log output.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects/{project_uid}/environments/{env_uid}/deployments/{deploy_uid}/server-logs:
    get:
      operationId: getServerLogs
      summary: Get server logs
      description: Retrieves server-side runtime logs for a deployed environment, useful for debugging server-side rendering issues and monitoring application runtime behavior.
      tags:
      - Deployments
      parameters:
      - $ref: '#/components/parameters/ProjectUid'
      - $ref: '#/components/parameters/EnvUid'
      - $ref: '#/components/parameters/DeployUid'
      responses:
        '200':
          description: The server runtime logs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  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'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    DeploymentList:
      type: object
      description: A list of deployments.
      properties:
        data:
          type: array
          description: Array of deployment objects.
          items:
            $ref: '#/components/schemas/Deployment'
    LogEntry:
      type: object
      description: A single log line entry.
      properties:
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the log entry.
        level:
          type: string
          description: Log level.
          enum:
          - info
          - warn
          - error
          - debug
        message:
          type: string
          description: The log message content.
    LogResponse:
      type: object
      description: Log output from a deployment or server.
      properties:
        logs:
          type: array
          description: Array of log line entries.
          items:
            $ref: '#/components/schemas/LogEntry'
    CreateDeploymentRequest:
      type: object
      description: Parameters for triggering a new deployment.
      properties:
        upload_uid:
          type: string
          description: The UID or reference to the previously uploaded build artifact.
        branch:
          type: string
          description: The git branch to deploy from when using repository-linked deployments.
    Error:
      type: object
      description: Standard error response.
      properties:
        message:
          type: string
          description: Human-readable description of the error.
        error_code:
          type: integer
          description: Numeric error code.
    Deployment:
      type: object
      description: A deployment operation to a Launch environment.
      properties:
        uid:
          type: string
          description: Unique identifier of the deployment.
        status:
          type: string
          description: Current status of the deployment.
          enum:
          - queued
          - building
          - deploying
          - live
          - failed
          - cancelled
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the deployment was created.
        completed_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the deployment completed.
  parameters:
    EnvUid:
      name: env_uid
      in: path
      required: true
      description: The unique identifier of the deployment environment.
      schema:
        type: string
    ProjectUid:
      name: project_uid
      in: path
      required: true
      description: The unique identifier of the Launch project.
      schema:
        type: string
    DeployUid:
      name: deploy_uid
      in: path
      required: true
      description: The unique identifier of the deployment.
      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