CircleCI Project API

openapi: 3.1.0
info:
  title: CircleCI REST API v1 Artifact Project API
  description: The CircleCI REST API v1 is the legacy API that provides access to build information, project details, and user data. While still available, CircleCI recommends migrating to the v2 API for newer features and improved functionality. The v1 API supports operations for retrieving build details, triggering builds, managing SSH keys, and accessing test metadata. Authentication is handled through API tokens passed as query parameters or HTTP headers.
  version: '1.1'
  contact:
    name: CircleCI Support
    url: https://support.circleci.com
  termsOfService: https://circleci.com/terms-of-service/
servers:
- url: https://circleci.com/api/v1.1
  description: CircleCI Production API v1.1
security:
- apiToken: []
tags:
- name: Project
  description: Endpoints for listing followed projects and managing project settings.
paths:
  /projects:
    get:
      operationId: listProjects
      summary: List followed projects
      description: Returns a list of all projects the authenticated user follows, including recent build summaries for each project.
      tags:
      - Project
      responses:
        '200':
          description: Successfully retrieved projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          description: Unauthorized
  /project/{vcs-type}/{username}/{project}/follow:
    post:
      operationId: followProject
      summary: Follow a project
      description: Follows a project, adding it to the authenticated user's list of followed projects.
      tags:
      - Project
      parameters:
      - $ref: '#/components/parameters/VcsTypeParam'
      - $ref: '#/components/parameters/UsernameParam'
      - $ref: '#/components/parameters/ProjectParam'
      responses:
        '200':
          description: Project followed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  following:
                    type: boolean
                    description: Whether the project is now being followed
                  first_build:
                    $ref: '#/components/schemas/BuildSummary'
        '401':
          description: Unauthorized
  /project/{project-slug}:
    get:
      operationId: getProject
      summary: Get a project
      description: Returns a project by its slug, which is a triplet of the VCS type, organization name, and repository name.
      tags:
      - Project
      parameters:
      - $ref: '#/components/parameters/ProjectSlugParam'
      responses:
        '200':
          description: Successfully retrieved project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project_2'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /project/{project-slug}/checkout-key:
    get:
      operationId: listCheckoutKeys
      summary: List checkout keys
      description: Returns a paginated list of checkout keys for a given project.
      tags:
      - Project
      parameters:
      - $ref: '#/components/parameters/ProjectSlugParam'
      responses:
        '200':
          description: Successfully retrieved checkout keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutKeyList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createCheckoutKey
      summary: Create a checkout key
      description: Creates a new checkout key for the specified project. Only deploy keys and user keys are supported.
      tags:
      - Project
      parameters:
      - $ref: '#/components/parameters/ProjectSlugParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - type
              properties:
                type:
                  type: string
                  enum:
                  - deploy-key
                  - user-key
                  description: The type of checkout key to create
      responses:
        '201':
          description: Checkout key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutKey'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /project/{project-slug}/checkout-key/{fingerprint}:
    get:
      operationId: getCheckoutKey
      summary: Get a checkout key
      description: Returns a checkout key by its fingerprint.
      tags:
      - Project
      parameters:
      - $ref: '#/components/parameters/ProjectSlugParam'
      - $ref: '#/components/parameters/FingerprintParam'
      responses:
        '200':
          description: Successfully retrieved checkout key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutKey'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Checkout key not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteCheckoutKey
      summary: Delete a checkout key
      description: Deletes a checkout key by its fingerprint.
      tags:
      - Project
      parameters:
      - $ref: '#/components/parameters/ProjectSlugParam'
      - $ref: '#/components/parameters/FingerprintParam'
      responses:
        '200':
          description: Successfully deleted checkout key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /project/{project-slug}/envvar:
    get:
      operationId: listProjectEnvironmentVariables
      summary: List project environment variables
      description: Returns a paginated list of masked environment variables for a given project.
      tags:
      - Project
      parameters:
      - $ref: '#/components/parameters/ProjectSlugParam'
      responses:
        '200':
          description: Successfully retrieved environment variables
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectEnvVarList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createProjectEnvironmentVariable
      summary: Create a project environment variable
      description: Creates a new environment variable for the specified project.
      tags:
      - Project
      parameters:
      - $ref: '#/components/parameters/ProjectSlugParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - value
              properties:
                name:
                  type: string
                  description: The name of the environment variable
                value:
                  type: string
                  description: The value of the environment variable
      responses:
        '201':
          description: Environment variable created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectEnvVar'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /project/{project-slug}/envvar/{name}:
    get:
      operationId: getProjectEnvironmentVariable
      summary: Get a masked environment variable
      description: Returns a masked environment variable by name for the specified project.
      tags:
      - Project
      parameters:
      - $ref: '#/components/parameters/ProjectSlugParam'
      - name: name
        in: path
        required: true
        description: The name of the environment variable
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved environment variable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectEnvVar'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Environment variable not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteProjectEnvironmentVariable
      summary: Delete a project environment variable
      description: Deletes an environment variable from the specified project.
      tags:
      - Project
      parameters:
      - $ref: '#/components/parameters/ProjectSlugParam'
      - name: name
        in: path
        required: true
        description: The name of the environment variable
        schema:
          type: string
      responses:
        '200':
          description: Successfully deleted environment variable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CheckoutKeyList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CheckoutKey'
          description: List of checkout keys
        next_page_token:
          type: string
          description: Token for retrieving the next page
    MessageResponse:
      type: object
      properties:
        message:
          type: string
          description: A message describing the result of the operation
    ProjectEnvVar:
      type: object
      properties:
        name:
          type: string
          description: The name of the environment variable
        value:
          type: string
          description: The masked value of the environment variable
    CheckoutKey:
      type: object
      properties:
        public-key:
          type: string
          description: The public SSH key
        type:
          type: string
          enum:
          - deploy-key
          - github-user-key
          description: The type of checkout key
        fingerprint:
          type: string
          description: The MD5 fingerprint of the key
        preferred:
          type: boolean
          description: Whether this is the preferred checkout key
        created-at:
          type: string
          format: date-time
          description: When the key was created
    BuildSummary:
      type: object
      properties:
        build_url:
          type: string
          format: uri
          description: URL to view the build
        build_num:
          type: integer
          description: The build number
        status:
          type: string
          description: The build status
        vcs_revision:
          type: string
          description: The VCS revision
    Project_2:
      type: object
      properties:
        slug:
          type: string
          description: The project slug
        name:
          type: string
          description: The project name
        id:
          type: string
          format: uuid
          description: The unique identifier of the project
        organization_name:
          type: string
          description: The name of the organization
        organization_slug:
          type: string
          description: The slug of the organization
        organization_id:
          type: string
          format: uuid
          description: The ID of the organization
        vcs_info:
          type: object
          properties:
            vcs_url:
              type: string
              format: uri
              description: The VCS URL
            provider:
              type: string
              description: The VCS provider
            default_branch:
              type: string
              description: The default branch name
          description: Version control system information
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message
    Project:
      type: object
      properties:
        vcs_url:
          type: string
          format: uri
          description: The VCS URL of the project
        followed:
          type: boolean
          description: Whether the user follows this project
        username:
          type: string
          description: The organization or username
        reponame:
          type: string
          description: The repository name
        branches:
          type: object
          additionalProperties:
            type: object
            properties:
              recent_builds:
                type: array
                items:
                  $ref: '#/components/schemas/BuildSummary'
                description: Recent builds on this branch
          description: Branch information with recent builds
    ProjectEnvVarList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProjectEnvVar'
          description: List of environment variables
        next_page_token:
          type: string
          description: Token for retrieving the next page
  parameters:
    ProjectParam:
      name: project
      in: path
      required: true
      description: The repository name
      schema:
        type: string
    ProjectSlugParam:
      name: project-slug
      in: path
      required: true
      description: The project slug in the form vcs-slug/org-name/repo-name (e.g., gh/CircleCI-Public/api-preview-docs)
      schema:
        type: string
    VcsTypeParam:
      name: vcs-type
      in: path
      required: true
      description: The version control system type
      schema:
        type: string
        enum:
        - github
        - bitbucket
    UsernameParam:
      name: username
      in: path
      required: true
      description: The organization or user name
      schema:
        type: string
    FingerprintParam:
      name: fingerprint
      in: path
      required: true
      description: The fingerprint of the checkout key
      schema:
        type: string
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: Circle-Token
      description: Personal API token for authenticating with the CircleCI API. Can also be passed as a query parameter.
externalDocs:
  description: CircleCI API v1 Reference
  url: https://circleci.com/docs/api/v1/