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.
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