openapi: 3.1.0
info:
  title: CircleCI REST API v1
  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/
externalDocs:
  description: CircleCI API v1 Reference
  url: https://circleci.com/docs/api/v1/
servers:
  - url: https://circleci.com/api/v1.1
    description: CircleCI Production API v1.1
tags:
  - name: Artifact
    description: >-
      Endpoints for listing and downloading build artifacts.
  - name: Build
    description: >-
      Endpoints for retrieving build details, triggering builds, retrying
      builds, and canceling builds.
  - name: Project
    description: >-
      Endpoints for listing followed projects and managing project settings.
  - name: SSH Key
    description: >-
      Endpoints for managing SSH keys and checkout keys for projects.
  - name: Test Metadata
    description: >-
      Endpoints for retrieving test metadata collected during builds.
  - name: User
    description: >-
      Endpoints for retrieving information about the authenticated user.
security:
  - apiToken: []
paths:
  /me:
    get:
      operationId: getCurrentUser
      summary: Get authenticated user
      description: >-
        Returns information about the currently authenticated user,
        including name, login, and avatar URL.
      tags:
        - User
      responses:
        '200':
          description: Successfully retrieved user information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
  /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}:
    get:
      operationId: listProjectBuilds
      summary: List builds for a project
      description: >-
        Returns a list of the most recent builds for the specified project,
        with optional filtering by branch.
      tags:
        - Build
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
        - name: filter
          in: query
          description: Filter builds by status
          schema:
            type: string
            enum:
              - completed
              - successful
              - failed
              - running
        - name: limit
          in: query
          description: Number of builds to return (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 30
        - name: offset
          in: query
          description: Offset for pagination
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: Successfully retrieved builds
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Build'
        '401':
          description: Unauthorized
    post:
      operationId: triggerBuild
      summary: Trigger a new build
      description: >-
        Triggers a new build for the specified project. Optionally specify
        a branch, revision, or build parameters.
      tags:
        - Build
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tag:
                  type: string
                  description: The tag to build
                revision:
                  type: string
                  description: The specific revision to build
                branch:
                  type: string
                  description: The branch to build
                parallel:
                  type: integer
                  description: Number of parallel containers
                build_parameters:
                  type: object
                  additionalProperties:
                    type: string
                  description: Additional build parameters
      responses:
        '201':
          description: Build triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildSummary'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /project/{vcs-type}/{username}/{project}/tree/{branch}:
    post:
      operationId: triggerBranchBuild
      summary: Trigger a build on a branch
      description: >-
        Triggers a new build on the specified branch of the project.
      tags:
        - Build
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
        - name: branch
          in: path
          required: true
          description: The branch to build
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                parallel:
                  type: integer
                  description: Number of parallel containers
                revision:
                  type: string
                  description: The specific revision to build
                build_parameters:
                  type: object
                  additionalProperties:
                    type: string
                  description: Additional build parameters
      responses:
        '201':
          description: Build triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildSummary'
        '401':
          description: Unauthorized
  /project/{vcs-type}/{username}/{project}/{build_num}:
    get:
      operationId: getBuild
      summary: Get build details
      description: >-
        Returns detailed information about a specific build, including
        its status, steps, and timing information.
      tags:
        - Build
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
        - $ref: '#/components/parameters/BuildNumParam'
      responses:
        '200':
          description: Successfully retrieved build details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildDetail'
        '401':
          description: Unauthorized
        '404':
          description: Build not found
  /project/{vcs-type}/{username}/{project}/{build_num}/retry:
    post:
      operationId: retryBuild
      summary: Retry a build
      description: >-
        Retries a build using the same configuration and revision as
        the original build.
      tags:
        - Build
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
        - $ref: '#/components/parameters/BuildNumParam'
      responses:
        '200':
          description: Build retried successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildSummary'
        '401':
          description: Unauthorized
  /project/{vcs-type}/{username}/{project}/{build_num}/cancel:
    post:
      operationId: cancelBuild
      summary: Cancel a build
      description: >-
        Cancels a running build.
      tags:
        - Build
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
        - $ref: '#/components/parameters/BuildNumParam'
      responses:
        '200':
          description: Build cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildSummary'
        '401':
          description: Unauthorized
  /project/{vcs-type}/{username}/{project}/{build_num}/artifacts:
    get:
      operationId: listBuildArtifacts
      summary: List artifacts for a build
      description: >-
        Returns a list of artifacts produced by the specified build.
      tags:
        - Artifact
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
        - $ref: '#/components/parameters/BuildNumParam'
      responses:
        '200':
          description: Successfully retrieved artifacts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Artifact'
        '401':
          description: Unauthorized
  /project/{vcs-type}/{username}/{project}/latest/artifacts:
    get:
      operationId: listLatestArtifacts
      summary: List latest build artifacts
      description: >-
        Returns artifacts from the latest build of the project,
        optionally filtered by branch.
      tags:
        - Artifact
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
        - name: branch
          in: query
          description: Filter artifacts by branch name
          schema:
            type: string
        - name: filter
          in: query
          description: Filter artifacts by status
          schema:
            type: string
            enum:
              - completed
              - successful
              - failed
      responses:
        '200':
          description: Successfully retrieved latest artifacts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Artifact'
        '401':
          description: Unauthorized
  /project/{vcs-type}/{username}/{project}/{build_num}/tests:
    get:
      operationId: listBuildTests
      summary: List test metadata for a build
      description: >-
        Returns test metadata collected from the specified build,
        sourced from JUnit XML or similar test result files.
      tags:
        - Test Metadata
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
        - $ref: '#/components/parameters/BuildNumParam'
      responses:
        '200':
          description: Successfully retrieved test metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  tests:
                    type: array
                    items:
                      $ref: '#/components/schemas/TestMetadata'
                    description: List of test results
        '401':
          description: Unauthorized
  /project/{vcs-type}/{username}/{project}/ssh-key:
    post:
      operationId: addSSHKey
      summary: Add an SSH key
      description: >-
        Adds an SSH key to the specified project for use in builds.
      tags:
        - SSH Key
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - hostname
                - private_key
              properties:
                hostname:
                  type: string
                  description: The hostname the key is associated with
                private_key:
                  type: string
                  description: The private key in PEM format
      responses:
        '200':
          description: SSH key added successfully
        '401':
          description: Unauthorized
  /project/{vcs-type}/{username}/{project}/checkout-key:
    get:
      operationId: listCheckoutKeys
      summary: List checkout keys
      description: >-
        Returns a list of checkout keys for the specified project.
      tags:
        - SSH Key
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
      responses:
        '200':
          description: Successfully retrieved checkout keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CheckoutKey'
        '401':
          description: Unauthorized
    post:
      operationId: createCheckoutKey
      summary: Create a checkout key
      description: >-
        Creates a new checkout key for the specified project.
      tags:
        - SSH Key
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - deploy-key
                    - github-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
  /project/{vcs-type}/{username}/{project}/checkout-key/{fingerprint}:
    get:
      operationId: getCheckoutKey
      summary: Get a checkout key
      description: >-
        Returns a checkout key by its fingerprint.
      tags:
        - SSH Key
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
        - name: fingerprint
          in: path
          required: true
          description: The fingerprint of the checkout key
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved checkout key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutKey'
        '401':
          description: Unauthorized
        '404':
          description: Checkout key not found
    delete:
      operationId: deleteCheckoutKey
      summary: Delete a checkout key
      description: >-
        Deletes a checkout key by its fingerprint.
      tags:
        - SSH Key
      parameters:
        - $ref: '#/components/parameters/VcsTypeParam'
        - $ref: '#/components/parameters/UsernameParam'
        - $ref: '#/components/parameters/ProjectParam'
        - name: fingerprint
          in: path
          required: true
          description: The fingerprint of the checkout key
          schema:
            type: string
      responses:
        '200':
          description: Checkout key deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Confirmation message
        '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
  /recent-builds:
    get:
      operationId: listRecentBuilds
      summary: List recent builds across all projects
      description: >-
        Returns a list of the most recent builds across all followed
        projects for the authenticated user.
      tags:
        - Build
      parameters:
        - name: limit
          in: query
          description: Number of builds to return (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 30
        - name: offset
          in: query
          description: Offset for pagination
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: Successfully retrieved recent builds
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Build'
        '401':
          description: Unauthorized
components:
  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.
  parameters:
    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
    ProjectParam:
      name: project
      in: path
      required: true
      description: The repository name
      schema:
        type: string
    BuildNumParam:
      name: build_num
      in: path
      required: true
      description: The build number
      schema:
        type: integer
  schemas:
    User:
      type: object
      properties:
        login:
          type: string
          description: The login name of the user
        name:
          type: string
          description: The display name of the user
        avatar_url:
          type: string
          format: uri
          description: URL of the user avatar
        admin:
          type: boolean
          description: Whether the user is an admin
        all_emails:
          type: array
          items:
            type: string
            format: email
          description: All email addresses associated with the user
        selected_email:
          type: string
          format: email
          description: The user selected email address
        days_left_in_trial:
          type: integer
          description: Days remaining in trial
        parallelism:
          type: integer
          description: Default parallelism setting
        created_at:
          type: string
          format: date-time
          description: When the user account was created
    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
    Build:
      type: object
      properties:
        vcs_url:
          type: string
          format: uri
          description: The VCS URL
        build_url:
          type: string
          format: uri
          description: URL to view the build in CircleCI
        build_num:
          type: integer
          description: The build number
        branch:
          type: string
          description: The branch that was built
        vcs_revision:
          type: string
          description: The VCS revision (commit SHA)
        committer_name:
          type: string
          description: Name of the committer
        committer_email:
          type: string
          format: email
          description: Email of the committer
        subject:
          type: string
          description: The commit message subject
        body:
          type: string
          description: The commit message body
        why:
          type: string
          description: Why the build was triggered
        status:
          type: string
          enum:
            - retried
            - canceled
            - infrastructure_fail
            - timedout
            - not_run
            - running
            - failed
            - queued
            - scheduled
            - not_running
            - no_tests
            - fixed
            - success
          description: The build status
        outcome:
          type: string
          enum:
            - canceled
            - infrastructure_fail
            - timedout
            - failed
            - no_tests
            - success
          description: The build outcome
        start_time:
          type: string
          format: date-time
          description: When the build started
        stop_time:
          type: string
          format: date-time
          description: When the build stopped
        build_time_millis:
          type: integer
          description: Total build time in milliseconds
        queued_at:
          type: string
          format: date-time
          description: When the build was queued
        lifecycle:
          type: string
          enum:
            - queued
            - scheduled
            - not_run
            - not_running
            - running
            - finished
          description: The build lifecycle phase
        username:
          type: string
          description: The organization or username
        reponame:
          type: string
          description: The repository name
    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
    BuildDetail:
      allOf:
        - $ref: '#/components/schemas/Build'
        - type: object
          properties:
            steps:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    description: The step name
                  actions:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: The action name
                        type:
                          type: string
                          description: The action type
                        status:
                          type: string
                          description: The action status
                        start_time:
                          type: string
                          format: date-time
                          description: When the action started
                        end_time:
                          type: string
                          format: date-time
                          description: When the action ended
                        run_time_millis:
                          type: integer
                          description: Action run time in milliseconds
                        output_url:
                          type: string
                          format: uri
                          description: URL to the action output
                    description: Actions within the step
              description: Build steps
            circle_yml:
              type: object
              description: The parsed CircleCI configuration
            messages:
              type: array
              items:
                type: string
              description: Build messages
            node:
              type: array
              items:
                type: object
                properties:
                  image_id:
                    type: string
                    description: The image ID used
                  port:
                    type: integer
                    description: The SSH port
                  public_ip_addr:
                    type: string
                    description: The public IP address
                  username:
                    type: string
                    description: The SSH username
              description: Node information for SSH access
    Artifact:
      type: object
      properties:
        path:
          type: string
          description: The artifact path
        pretty_path:
          type: string
          description: Human-readable artifact path
        node_index:
          type: integer
          description: The node index that produced this artifact
        url:
          type: string
          format: uri
          description: URL to download the artifact
    TestMetadata:
      type: object
      properties:
        message:
          type: string
          description: The test message
        file:
          type: string
          description: The file containing the test
        source:
          type: string
          description: The source of the test
        run_time:
          type: number
          format: float
          description: The run time of the test in seconds
        result:
          type: string
          enum:
            - success
            - failure
            - skipped
          description: The test result
        name:
          type: string
          description: The name of the test
        classname:
          type: string
          description: The class name of the test
    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 key
        login:
          type: string
          description: The login associated with the key
        time:
          type: string
          format: date-time
          description: When the key was created