contentstack Projects API

openapi: 3.1.0
info:
  title: Contentstack Analytics Accounts Projects 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: Projects
  description: Automation projects are containers for automations within a Contentstack organization. Each project groups related automations and can have its own variables and account connections.
paths:
  /v1/organizations/{organization_uid}/projects:
    get:
      operationId: getAllProjects
      summary: Get all projects
      description: Retrieves all automation projects within the specified organization. Each project contains automations, variables, and external service account connections.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      responses:
        '200':
          description: A list of automation projects in the organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProject
      summary: Create a project
      description: Creates a new automation project within the specified organization. Projects serve as organizational containers for automations and shared configuration.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '201':
          description: The newly created project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/organizations/{organization_uid}/projects/{project_uid}:
    get:
      operationId: getProject
      summary: Get a project
      description: Retrieves details for a specific automation project including its metadata, creation date, and current status.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/ProjectUid'
      responses:
        '200':
          description: The requested project details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateProject
      summary: Update a project
      description: Updates the name or description of an existing automation project.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/ProjectUid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '200':
          description: The updated project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteProject
      summary: Delete a project
      description: Permanently deletes an automation project and all its automations, variables, and configuration. This action is irreversible.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/OrganizationUid'
      - $ref: '#/components/parameters/ProjectUid'
      responses:
        '200':
          description: Project deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /projects:
    get:
      operationId: getAllProjects
      summary: Get all projects
      description: Retrieves all Launch projects accessible to the authenticated user or organization. Returns project metadata including names, creation dates, and environment counts.
      tags:
      - Projects
      responses:
        '200':
          description: A list of Launch projects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectList_2'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProject
      summary: Create a project
      description: Creates a new Launch project for deploying a web application. Projects serve as the top-level container for environments and deployments.
      tags:
      - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest_2'
      responses:
        '201':
          description: The newly created Launch project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /projects/{project_uid}:
    get:
      operationId: getProject
      summary: Get a project
      description: Retrieves the details of a specific Launch project including its configuration, current status, and linked Contentstack stack.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/ProjectUid_2'
      responses:
        '200':
          description: The requested Launch project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project_2'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateProject
      summary: Update a project
      description: Updates the configuration of an existing Launch project such as its name, description, or framework settings.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/ProjectUid_2'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest_2'
      responses:
        '200':
          description: The updated Launch project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteProject
      summary: Delete a project
      description: Permanently deletes a Launch project and all its environments and deployment history. This action is irreversible.
      tags:
      - Projects
      parameters:
      - $ref: '#/components/parameters/ProjectUid_2'
      responses:
        '200':
          description: Project deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    ProjectUid:
      name: project_uid
      in: path
      required: true
      description: The unique identifier of the automation project.
      schema:
        type: string
    OrganizationUid:
      name: organization_uid
      in: path
      required: true
      description: The unique identifier of the organization.
      schema:
        type: string
    ProjectUid_2:
      name: project_uid
      in: path
      required: true
      description: The unique identifier of the Launch project.
      schema:
        type: string
  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:
    CreateProjectRequest:
      type: object
      description: Parameters for creating or updating a project.
      required:
      - name
      properties:
        name:
          type: string
          description: Display name for the project.
        description:
          type: string
          description: Description of the project's purpose.
    Project_2:
      type: object
      description: A Contentstack Launch project for web application deployment.
      properties:
        uid:
          type: string
          description: Unique identifier of the project.
        name:
          type: string
          description: Display name of the project.
        description:
          type: string
          description: Description of the project.
        framework:
          type: string
          description: The web framework used by the project (e.g., next, gatsby, nuxt).
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the project was created.
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the project was last updated.
    ProjectList:
      type: object
      description: A list of automation projects.
      properties:
        data:
          type: array
          description: Array of project objects.
          items:
            $ref: '#/components/schemas/Project'
    ProjectList_2:
      type: object
      description: A list of Launch projects.
      properties:
        data:
          type: array
          description: Array of Launch project objects.
          items:
            $ref: '#/components/schemas/Project_2'
    Project:
      type: object
      description: An automation project within a Contentstack organization.
      properties:
        uid:
          type: string
          description: Unique identifier of the project.
        name:
          type: string
          description: Display name of the project.
        description:
          type: string
          description: Description of the project's purpose.
        organization_uid:
          type: string
          description: UID of the organization that owns the project.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the project was created.
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the project was last updated.
    CreateProjectRequest_2:
      type: object
      description: Parameters for creating or updating a Launch project.
      required:
      - name
      properties:
        name:
          type: string
          description: Display name for the project.
        description:
          type: string
          description: Description of the project.
        framework:
          type: string
          description: The web framework for the project.
    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.
  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