CircleCI Project API

openapi: 3.2.0
info:
  title: Circleci Project API
  contact:
    name: CircleCI Support
    url: https://support.circleci.com
  termsOfService: https://circleci.com/terms-of-service/
  version: '1.0'
  description: 'Operations tagged Project across 2 of this provider''s published API definitions: circleci-rest-api-v1-openapi.yml, circleci-rest-api-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://circleci.com/api/v1.1
  description: CircleCI Production API v1.1
- url: https://circleci.com/api/v2
  description: CircleCI Production API
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
    servers:
    - url: https://circleci.com/api/v1.1
      description: CircleCI Production API v1.1
  /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
    servers:
    - url: https://circleci.com/api/v1.1
      description: CircleCI Production API v1.1
  /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'
    servers:
    - url: https://circleci.com/api/v2
      description: CircleCI Production API
  /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'
    servers:
    - url: https://circleci.com/api/v2
      description: CircleCI Production API
  /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'
    servers:
    - url: https://circleci.com/api/v2
      description: CircleCI Production API
  /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'
    servers:
    - url: https://circleci.com/api/v2
      description: CircleCI Production API
  /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'
    servers:
    - url: https://circleci.com/api/v2
      description: CircleCI Production API
components:
  schemas:
    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
    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
    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
    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
    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
    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
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: A human-readable error message
    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
  parameters:
    ProjectParam:
      name: project
      in: path
      required: true
      description: The repository name
      schema:
        type: string
    UsernameParam:
      name: username
      in: path
      required: true
      description: The organization or user name
      schema:
        type: string
    VcsTypeParam:
      name: vcs-type
      in: path
      required: true
      description: The version control system type
      schema:
        type: string
        enum:
        - github
        - bitbucket
    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
    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.
    basicAuth:
      type: http
      scheme: basic
      description: HTTP basic authentication using a personal API token as the username with an empty password.
x-refined-from:
- circleci-rest-api-v1-openapi.yml
- circleci-rest-api-v2-openapi.yml