Continuous Integration — entry 004 of 5

CircleCI

Verified Jul 2026

CircleCI's REST API triggers and inspects pipelines, workflows, and jobs, and manages projects, contexts, and self-hosted runners. The stored v1-reference docs URL now 404s live — CircleCI has fully moved API documentation to v2, whose own v1 docs page carries a banner recommending migration to v2 endpoints — so the URL was corrected to the current v2 reference. Authentication is reconfirmed as a personal API token: an unauthenticated GET to api/v2/me returned 401, and that same response (plus its OPTIONS preflight) carried no access-control-allow-origin header at all despite a Vary: Origin header, resolving CORS to closed rather than open. CircleCI's pricing page offers a Free plan (30,000 monthly credits, more for open source) alongside paid Performance plans, making it freemium.

ci-cddevopsautomationpipelinesbuild-automation

Visit circleci.com ↗Pricing ↗Status ↗More Continuous Integration

AuthenticationAPI KeySign up with the provider to obtain credentials.

HTTPSSupportedTraffic is encrypted in transit.

CORSDisabledBrowser calls need a server-side proxy.

PricingFreemiumA usable free tier exists, with paid plans for more volume.

FormatsJSONResponses can be requested as JSON.

GreatAPIs Score

Score81out of 100

Authentication15/25API key required

Pricing17/20Freemium tier available

Docs20/20Machine-readable spec file bundled

Formats9/15Single response format

Freshness20/20Verified within 6 months

Embed this badge

<a href="https://greatapis.com/api/circleci/"><img src="https://greatapis.com/badge/circleci.svg" alt="Scored 81 on greatapis.com"></a>

Auth quickstart

Get a key at the provider
Send it on every request as a headerAuthorization: <key>
The exact header isn't documented — Authorization is a common default; confirm in the provider's docs.

Stored keyNo key stored

Your key is stored only in this browser (localStorage) and sent directly to the API — never to greatapis.

Endpoints

Servers

https://circleci.com/api/v2

Auth

api_key_headerbearer_authbasic_authapi_key_query

Context10

Endpoints relating to [contexts](https://circleci.com/docs/contexts/). Use contexts to secure and share environment variables.

GET/contextList contexts

Parameters

Name	In	Required	Type
`owner-id`	query	no	string
`owner-slug`	query	no	string
`owner-type`	query	no	string
`page-token`	query	no	string

Responses

Status	Description	Schema
`200`	A paginated list of contexts	`context_list`
`401`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

POST/contextCreate a new context

Request body

application/json — context_created

Responses

Status	Description	Schema
`200`	The new context	—
`401`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

GET/context/{context_id}Get a context

Parameters

Name	In	Required	Type
`context_id`	path	yes	string

Responses

Status	Description	Schema
`200`	The context	`context`
`401`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

DELETE/context/{context_id}Delete a context

Parameters

Name	In	Required	Type
`context_id`	path	yes	string

Responses

Status	Description	Schema
`200`	A confirmation message	`delete_context_response`
`401`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

GET/context/{context_id}/environment-variableList environment variables

Parameters

Name	In	Required	Type
`context_id`	path	yes	string
`page-token`	query	no	string

Responses

Status	Description	Schema
`200`	A paginated list of environment variables	`env_var_list`
`401`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

PUT/context/{context_id}/environment-variable/{env_var_name}Add or update an environment variable

Parameters

Name	In	Required	Type
`context_id`	path	yes	string
`env_var_name`	path	yes	string

Request body

application/json

Responses

Status	Description	Schema
`200`	The new environment variable	`update_env_var`
`401`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

DELETE/context/{context_id}/environment-variable/{env_var_name}Remove an environment variable

Parameters

Name	In	Required	Type
`context_id`	path	yes	string
`env_var_name`	path	yes	string

Responses

Status	Description	Schema
`200`	A confirmation message	`delete_env_var`
`401`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

GET/context/{context_id}/restrictionsGet context restrictions

Parameters

Name	In	Required	Type
`context_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Successful response.	`context_project_restrictions_list`
`400`	—	—
`401`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

POST/context/{context_id}/restrictionsCreate context restriction

Parameters

Name	In	Required	Type
`context_id`	path	yes	string

Request body

application/json (required)

Responses

Status	Description	Schema
`201`	Successful response.	`restriction_created`
`400`	Bad request.	—
`401`	—	—
`404`	—	—
`409`	Request conflict.	—
`429`	—	—
`500`	—	—

DELETE/context/{context_id}/restrictions/{restriction_id}Delete context restriction

Parameters

Name	In	Required	Type
`context_id`	path	yes	string
`restriction_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Successful response.	`restriction_deleted`
`400`	—	—
`401`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

Insights10

Endpoints relating to [Insights](https://circleci.com/docs/insights/). Use Insights to monitor credit and compute usage for your projects.

GET/insights/pages/{project-slug}/summaryGet summary metrics and trends for a project across it's workflows and branches

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`reporting-window`	query	no	string
`branches`	query	no	object
`workflow-names`	query	no	object

Responses

Status	Description	Schema
`200`	Aggregated summary metrics and trends by workflow and branches	—
`default`	Error response.	—

GET/insights/time-series/{project-slug}/workflows/{workflow-name}/jobsJob timeseries data

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`workflow-name`	path	yes	string
`branch`	query	no	string
`granularity`	query	no	string
`start-date`	query	no	string
`end-date`	query	no	string

Responses

Status	Description	Schema
`200`	An array of timeseries data, one entry per job.	—
`default`	Error response.	—

GET/insights/{org-slug}/summaryGet summary metrics with trends for the entire org, and for each project.

Parameters

Name	In	Required	Type
`org-slug`	path	yes	string
`reporting-window`	query	no	string
`project-names`	query	no	object

Responses

Status	Description	Schema
`200`	summary metrics with trends for an entire org and it's projects.	—
`default`	Error response.	—

GET/insights/{project-slug}/branchesGet all branches for a project

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`workflow-name`	query	no	string

Responses

Status	Description	Schema
`200`	A list of branches for a project	—
`default`	Error response.	—

GET/insights/{project-slug}/flaky-testsGet flaky tests for a project

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string

Responses

Status	Description	Schema
`200`	A list of flaky tests for a project	—
`default`	Error response.	—

GET/insights/{project-slug}/workflowsGet summary metrics for a project's workflows

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`page-token`	query	no	string
`all-branches`	query	no	boolean
`branch`	query	no	string
`reporting-window`	query	no	string

Responses

Status	Description	Schema
`200`	A paginated list of summary metrics by workflow	—
`default`	Error response.	—

GET/insights/{project-slug}/workflows/{workflow-name}Get recent runs of a workflow

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`workflow-name`	path	yes	string
`all-branches`	query	no	boolean
`branch`	query	no	string
`page-token`	query	no	string
`start-date`	query	no	string
`end-date`	query	no	string

Responses

Status	Description	Schema
`200`	A paginated list of recent workflow runs	—
`default`	Error response.	—

GET/insights/{project-slug}/workflows/{workflow-name}/jobsGet summary metrics for a project workflow's jobs.

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`workflow-name`	path	yes	string
`page-token`	query	no	string
`all-branches`	query	no	boolean
`branch`	query	no	string
`reporting-window`	query	no	string
`job-name`	query	no	string

Responses

Status	Description	Schema
`200`	A paginated list of summary metrics by workflow job.	—
`default`	Error response.	—

GET/insights/{project-slug}/workflows/{workflow-name}/summaryGet metrics and trends for workflows

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`workflow-name`	path	yes	string
`all-branches`	query	no	boolean
`branch`	query	no	string

Responses

Status	Description	Schema
`200`	Metrics and trends for a workflow	—
`default`	Error response.	—

GET/insights/{project-slug}/workflows/{workflow-name}/test-metricsGet test metrics for a project's workflows

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`workflow-name`	path	yes	string
`branch`	query	no	string
`all-branches`	query	no	boolean

Responses

Status	Description	Schema
`200`	A list of test metrics by workflow	—
`default`	Error response.	—

User3

A set of endpoints you can use to get information about a specific user.

GET/meUser Information

Responses

Status	Description	Schema
`200`	User login information.	—
`default`	Error response.	—

GET/me/collaborationsCollaborations

Responses

Status	Description	Schema
`200`	Collaborations	—
`default`	Error response.	—

GET/user/{id}User Information

Parameters

Name	In	Required	Type
`id`	path	yes	string

Responses

Status	Description	Schema
`200`	User login information.	—
`default`	Error response.	—

Pipeline11

Endpoints relating to [pipelines](https://circleci.com/docs/pipelines/). Get information about your pipelines. Trigger or continue a pipeline.

GET/pipelineGet a list of pipelines

Parameters

Name	In	Required	Type
`org-slug`	query	no	string
`page-token`	query	no	string
`mine`	query	no	boolean

Responses

Status	Description	Schema
`200`	A sequence of pipelines.	—
`default`	Error response.	—

POST/pipeline/continueContinue a pipeline

Request body

application/json

Responses

Status	Description	Schema
`200`	A confirmation message.	—
`default`	Error response.	—

GET/pipeline/{pipeline-id}Get a pipeline by ID

Parameters

Name	In	Required	Type
`pipeline-id`	path	yes	string

Responses

Status	Description	Schema
`200`	A pipeline object.	—
`default`	Error response.	—

GET/pipeline/{pipeline-id}/configGet a pipeline's configuration

Parameters

Name	In	Required	Type
`pipeline-id`	path	yes	string

Responses

Status	Description	Schema
`200`	The configuration strings for the pipeline.	—
`default`	Error response.	—

GET/pipeline/{pipeline-id}/workflowGet a pipeline's workflows

Parameters

Name	In	Required	Type
`pipeline-id`	path	yes	string
`page-token`	query	no	string

Responses

Status	Description	Schema
`200`	A paginated list of workflow objects.	—
`default`	Error response.	—

GET/pipeline/{pipeline_id}/valuesGet pipeline values for a pipeline

Parameters

Name	In	Required	Type
`pipeline_id`	path	yes	string

Responses

Status	Description	Schema
`200`	A JSON object of pipeline values.	`pipelineValues`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

GET/project/{project-slug}/pipelineGet all pipelines

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`branch`	query	no	string
`page-token`	query	no	string

Responses

Status	Description	Schema
`200`	A sequence of pipelines.	—
`default`	Error response.	—

POST/project/{project-slug}/pipelineTrigger a new pipeline

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string

Request body

application/json

Responses

Status	Description	Schema
`201`	The created pipeline.	—
`default`	Error response.	—

GET/project/{project-slug}/pipeline/mineGet your pipelines

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`page-token`	query	no	string

Responses

Status	Description	Schema
`200`	A sequence of pipelines.	—
`default`	Error response.	—

GET/project/{project-slug}/pipeline/{pipeline-number}Get a pipeline by pipeline number

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`pipeline-number`	path	yes	—

Responses

Status	Description	Schema
`200`	A pipeline object.	—
`default`	Error response.	—

POST/project/{provider}/{organization}/{project}/pipeline/run[Recommended] Trigger a new pipeline

Parameters

Name	In	Required	Type
`provider`	path	yes	string
`organization`	path	yes	string
`project`	path	yes	string

Request body

application/json — triggerPipelineRequest

Responses

Status	Description	Schema
`200`	Successful response with no created pipeline.	`pipelineNotTriggeredResponse`
`201`	Successful response.	`pipelineTriggeredResponse`
`400`	—	—
`401`	—	—
`404`	—	—

Job3

Endpoints relating to [jobs](https://circleci.com/docs/jobs-steps/). Get information about your jobs, retrieve job assets, cancel a job.

POST/jobs/{job-id}/cancelCancel job by job ID

Parameters

Name	In	Required	Type
`job-id`	path	yes	string

Responses

Status	Description	Schema
`200`	Job cancelled successfully.	—
`400`	Bad request error.	—
`401`	Unauthorized error.	—
`403`	Forbidden error.	—
`404`	Job not found error.	—
`default`	Error response.	—

GET/jobs/{job_id}Get a job

Parameters

Name	In	Required	Type
`job_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Job fetched successfully	`getJobResponse`
`400`	—	—
`401`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

POST/project/{project-slug}/job/{job-number}/cancelCancel job by job number

Parameters

Name	In	Required	Type
`job-number`	path	yes	—
`project-slug`	path	yes	string

Responses

Status	Description	Schema
`200`		—
`default`	Error response.	—

Workflow5

Endpoints relating to [workflows](https://circleci.com/docs/workflows/). Get information about your workflows, or interact with them to rerun, cancel or approve a job.

GET/workflow/{id}Get a workflow

Parameters

Name	In	Required	Type
`id`	path	yes	string

Responses

Status	Description	Schema
`200`	A workflow object.	`workflow`
`400`	—	—
`401`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

POST/workflow/{id}/approve/{approval_request_id}Approve a job

Parameters

Name	In	Required	Type
`approval_request_id`	path	yes	string
`id`	path	yes	string

Responses

Status	Description	Schema
`202`	A confirmation message.	—
`default`	Error response.	—

POST/workflow/{id}/cancelCancel a workflow

Parameters

Name	In	Required	Type
`id`	path	yes	string

Responses

Status	Description	Schema
`202`	A confirmation message.	—
`default`	Error response.	—

GET/workflow/{id}/jobGet a workflow's jobs

Parameters

Name	In	Required	Type
`id`	path	yes	string

Responses

Status	Description	Schema
`200`	A paginated sequence of jobs.	—
`default`	Error response.	—

POST/workflow/{id}/rerunRerun a workflow

Parameters

Name	In	Required	Type
`id`	path	yes	string

Request body

application/json

Responses

Status	Description	Schema
`202`	A confirmation message.	—
`default`	Error response.	—

OIDC Token Management6

Endpoints related to manage oidc identity tokens

GET/org/{orgID}/oidc-custom-claimsGet org-level claims

Parameters

Name	In	Required	Type
`orgID`	path	yes	string

Responses

Status	Description	Schema
`200`	Claims successfully fetched.	`ClaimResponse`
`400`	—	—
`403`	—	—
`500`	—	—

PATCH/org/{orgID}/oidc-custom-claimsPatch org-level claims

Parameters

Name	In	Required	Type
`orgID`	path	yes	string

Request body

application/json — PatchClaimsRequest

Responses

Status	Description	Schema
`200`	Claims successfully patched.	`ClaimResponse`
`400`	—	—
`403`	—	—
`500`	—	—

DELETE/org/{orgID}/oidc-custom-claimsDelete org-level claims

Parameters

Name	In	Required	Type
`orgID`	path	yes	string
`claims`	query	yes	string

Responses

Status	Description	Schema
`200`	Claims successfully deleted.	`ClaimResponse`
`400`	—	—
`403`	—	—
`500`	—	—

GET/org/{orgID}/project/{projectID}/oidc-custom-claimsGet project-level claims

Parameters

Name	In	Required	Type
`orgID`	path	yes	string
`projectID`	path	yes	string

Responses

Status	Description	Schema
`200`	Claims successfully fetched.	`ClaimResponse`
`400`	—	—
`403`	—	—
`500`	—	—

PATCH/org/{orgID}/project/{projectID}/oidc-custom-claimsPatch project-level claims

Parameters

Name	In	Required	Type
`orgID`	path	yes	string
`projectID`	path	yes	string

Request body

application/json — PatchClaimsRequest

Responses

Status	Description	Schema
`200`	Claims successfully patched.	`ClaimResponse`
`400`	—	—
`403`	—	—
`500`	—	—

DELETE/org/{orgID}/project/{projectID}/oidc-custom-claimsDelete project-level claims

Parameters

Name	In	Required	Type
`orgID`	path	yes	string
`projectID`	path	yes	string
`claims`	query	yes	string

Responses

Status	Description	Schema
`200`	Claims successfully deleted.	`ClaimResponse`
`400`	—	—
`403`	—	—
`500`	—	—

Policy Management9

Endpoints related to managing policies and making policy decisions

GET/owner/{ownerID}/context/{context}/decisionRetrieves the owner's decision audit logs.

Parameters

Name	In	Required	Type
`ownerID`	path	yes	string
`context`	path	yes	string
`status`	query	no	string
`after`	query	no	string
`before`	query	no	string
`branch`	query	no	string
`project_id`	query	no	string
`build_number`	query	no	string
`offset`	query	no	integer

Responses

Status	Description	Schema
`200`	Decision logs successfully retrieved.	—
`400`	—	—
`401`	—	—
`403`	—	—
`500`	—	—

POST/owner/{ownerID}/context/{context}/decisionMakes a decision

Parameters

Name	In	Required	Type
`ownerID`	path	yes	string
`context`	path	yes	string

Request body

application/json

Responses

Status	Description	Schema
`200`	Decision rendered by applying the policy against the provided data. Response will be modeled by the data and rego processed.	`Decision`
`400`	The request is malformed	—
`401`	The request is unauthorized	—
`500`	Something unexpected happened on the server.	—

GET/owner/{ownerID}/context/{context}/decision/settingsGet the decision settings

Parameters

Name	In	Required	Type
`ownerID`	path	yes	string
`context`	path	yes	string

Responses

Status	Description	Schema
`200`	Decision settings successfully retrieved.	`DecisionSettings`
`400`	—	—
`401`	—	—
`403`	—	—
`500`	—	—

PATCH/owner/{ownerID}/context/{context}/decision/settingsSet the decision settings

Parameters

Name	In	Required	Type
`ownerID`	path	yes	string
`context`	path	yes	string

Request body

application/json — DecisionSettings

Responses

Status	Description	Schema
`200`	Decision settings successfully set.	`DecisionSettings`
`400`	—	—
`401`	—	—
`403`	—	—
`500`	—	—

GET/owner/{ownerID}/context/{context}/decision/{decisionID}Retrieves the owner's decision audit log by given decisionID

Parameters

Name	In	Required	Type
`ownerID`	path	yes	string
`context`	path	yes	string
`decisionID`	path	yes	string

Responses

Status	Description	Schema
`200`	Decision log successfully retrieved.	`DecisionLog`
`400`	—	—
`401`	—	—
`403`	—	—
`404`	There was no decision log found for given decision_id, and owner_id.	—
`500`	—	—

GET/owner/{ownerID}/context/{context}/decision/{decisionID}/policy-bundleRetrieves Policy Bundle for a given decision log ID

Parameters

Name	In	Required	Type
`ownerID`	path	yes	string
`context`	path	yes	string
`decisionID`	path	yes	string

Responses

Status	Description	Schema
`200`	Policy-Bundle retrieved successfully for given decision log ID	`PolicyBundle`
`400`	—	—
`401`	—	—
`403`	—	—
`404`	There was no decision log found for given decision_id, and owner_id.	—
`500`	—	—

GET/owner/{ownerID}/context/{context}/policy-bundleRetrieves Policy Bundle

Parameters

Name	In	Required	Type
`ownerID`	path	yes	string
`context`	path	yes	string

Responses

Status	Description	Schema
`200`	Policy-Bundle retrieved successfully.	`PolicyBundle`
`400`	—	—
`401`	—	—
`403`	—	—
`500`	—	—

POST/owner/{ownerID}/context/{context}/policy-bundleCreates policy bundle for the context

Parameters

Name	In	Required	Type
`ownerID`	path	yes	string
`context`	path	yes	string
`dry`	query	no	boolean

Request body

application/json — BundlePayload

Responses

Status	Description	Schema
`200`	Policy-Bundle diff successfully returned.	`BundleDiff`
`201`	Policy-Bundle successfully created.	`BundleDiff`
`400`	—	—
`401`	—	—
`403`	—	—
`413`	The request exceeds the maximum payload size for policy bundles ~2.5Mib	—
`500`	—	—

GET/owner/{ownerID}/context/{context}/policy-bundle/{policyName}Retrieves a policy document

Parameters

Name	In	Required	Type
`ownerID`	path	yes	string
`context`	path	yes	string
`policyName`	path	yes	string

Responses

Status	Description	Schema
`200`	Policy retrieved successfully.	`Policy`
`400`	—	—
`401`	—	—
`403`	—	—
`404`	There was no policy that was found with the given owner_id and policy name.	—
`500`	—	—

Deploy5

Endpoints related to deploy management.

GET/deploy/componentsList Components

Parameters

Name	In	Required	Type
`org-id`	query	yes	string
`project-id`	query	no	string
`page-size`	query	yes	integer
`page-token`	query	no	string

Responses

Status	Description	Schema
`200`	Paginated components list	`paginatedComponentList`
`400`	—	—
`404`	—	—
`500`	—	—

GET/deploy/components/{component_id}Get Component

Parameters

Name	In	Required	Type
`component_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Successful response.	`component`
`400`	—	—
`404`	—	—
`500`	—	—

GET/deploy/components/{component_id}/versionsList Component Versions

Parameters

Name	In	Required	Type
`component_id`	path	yes	string
`environment-id`	query	no	string

Responses

Status	Description	Schema
`200`	Paginated component versions list	`paginatedComponentVersionList`
`400`	—	—
`404`	—	—
`500`	—	—

GET/deploy/environmentsList Environments

Parameters

Name	In	Required	Type
`org-id`	query	yes	string
`page-size`	query	yes	integer
`page-token`	query	no	string

Responses

Status	Description	Schema
`200`	Paginated environments list	`paginatedEnvironmentList`
`400`	—	—
`404`	—	—
`500`	—	—

GET/deploy/environments/{environment_id}Get Environment

Parameters

Name	In	Required	Type
`environment_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Environment	`environment`
`400`	—	—
`404`	—	—
`500`	—	—

OTel3

[__EXPERIMENTAL__] Endpoints related to managing OpenTelemetry exporter configurations.

GET/otel/exporters🧪 List OTLP exporters

Parameters

Name	In	Required	Type
`org-id`	query	yes	string

Responses

Status	Description	Schema
`200`	List of OTLP exporters.	`exporterList`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

POST/otel/exporters🧪 Create an OTLP exporter

Request body

application/json — createExporterRequest (required)

Responses

Status	Description	Schema
`201`	OTLP exporter created.	`exporter`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

DELETE/otel/exporters/{otel_exporter_id}🧪 Delete an OTLP exporter

Parameters

Name	In	Required	Type
`otel_exporter_id`	path	yes	string

Responses

Status	Description	Schema
`204`	OTLP exporter deleted.	—
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

Pipeline Definition5

Endpoints related to creating and managing pipeline definitions.

GET/projects/{project_id}/pipeline-definitionsList pipeline definitions

Parameters

Name	In	Required	Type
`project_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Successful response.	`pipelineDefinitionList`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

POST/projects/{project_id}/pipeline-definitionsCreate pipeline definition

Parameters

Name	In	Required	Type
`project_id`	path	yes	string

Request body

application/json — createPipelineDefinitionRequest

Responses

Status	Description	Schema
`200`	Successful response.	`pipelineDefinition`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

GET/projects/{project_id}/pipeline-definitions/{pipeline_definition_id}Get pipeline definition

Parameters

Name	In	Required	Type
`project_id`	path	yes	string
`pipeline_definition_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Successful response.	`pipelineDefinition`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

PATCH/projects/{project_id}/pipeline-definitions/{pipeline_definition_id}Update pipeline definition

Parameters

Name	In	Required	Type
`project_id`	path	yes	string
`pipeline_definition_id`	path	yes	string

Request body

application/json — updatePipelineDefinitionRequest

Responses

Status	Description	Schema
`200`	Successful response.	`pipelineDefinition`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

DELETE/projects/{project_id}/pipeline-definitions/{pipeline_definition_id}Delete pipeline definition

Parameters

Name	In	Required	Type
`project_id`	path	yes	string
`pipeline_definition_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Successful response.	`pipelineDefinitionDeleted`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

Project13

Endpoints related to creating and managing a project.

POST/organization/{org-slug-or-id}/projectCreate a new project

Parameters

Name	In	Required	Type
`org-slug-or-id`	path	yes	string

Request body

application/json

Responses

Status	Description	Schema
`200`	The new project	—
`default`	Error response.	—

GET/project/{project-slug}Get a project

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string

Responses

Status	Description	Schema
`200`	A project object	—
`default`	Error response.	—

DELETE/project/{project-slug}Delete a project

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string

Responses

Status	Description	Schema
`200`	A confirmation message.	—
`default`	Error response.	—

GET/project/{project-slug}/checkout-keyGet all checkout keys

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`digest`	query	no	string

Responses

Status	Description	Schema
`200`	A sequence of checkout keys.	—
`default`	Error response.	—

POST/project/{project-slug}/checkout-keyCreate a new checkout key

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string

Request body

application/json

Responses

Status	Description	Schema
`201`	The checkout key.	—
`default`	Error response.	—

GET/project/{project-slug}/checkout-key/{fingerprint}Get a checkout key

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`fingerprint`	path	yes	string

Responses

Status	Description	Schema
`200`	The checkout key.	—
`default`	Error response.	—

DELETE/project/{project-slug}/checkout-key/{fingerprint}Delete a checkout key

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`fingerprint`	path	yes	string

Responses

Status	Description	Schema
`200`	A confirmation message.	—
`default`	Error response.	—

GET/project/{project-slug}/envvarList all environment variables

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string

Responses

Status	Description	Schema
`200`	A sequence of environment variables.	—
`default`	Error response.	—

POST/project/{project-slug}/envvarCreate an environment variable

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string

Request body

application/json

Responses

Status	Description	Schema
`201`	The environment variable.	—
`default`	Error response.	—

GET/project/{project-slug}/envvar/{name}Get a masked environment variable

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`name`	path	yes	string

Responses

Status	Description	Schema
`200`	The environment variable.	—
`default`	Error response.	—

DELETE/project/{project-slug}/envvar/{name}Delete an environment variable

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`name`	path	yes	string

Responses

Status	Description	Schema
`200`	A confirmation message.	—
`default`	Error response.	—

GET/project/{provider}/{organization}/{project}/settingsGet project settings

Parameters

Name	In	Required	Type
`provider`	path	yes	string
`organization`	path	yes	string
`project`	path	yes	string

Responses

Status	Description	Schema
`200`	Successful response.	`project_settings`
`401`	—	—
`403`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

PATCH/project/{provider}/{organization}/{project}/settingsUpdate project settings

Parameters

Name	In	Required	Type
`provider`	path	yes	string
`organization`	path	yes	string
`project`	path	yes	string

Request body

application/json — project_settings (required)

Responses

Status	Description	Schema
`200`	Successful response. Always includes the full advanced settings object. Returned even when the provided updates match the existing settings, but can also be returned when `oss: true` fails to set.	`project_settings`
`400`	Request is malformed, e.g. with improperly encoded JSON	—
`401`	—	—
`403`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

Rollback1

Endpoints related to creating and managing a rollback.

POST/projects/{project_id}/rollbackRollback a project

Parameters

Name	In	Required	Type
`project_id`	path	yes	string

Request body

application/json — rollbackProjectRequest (required)

Responses

Status	Description	Schema
`202`	Rollback request accepted.	`rollbackProjectResponse`
`400`	—	—
`404`	—	—
`409`	—	—
`500`	—	—

Trigger5

Endpoints related to creating and managing triggers.

GET/projects/{project_id}/pipeline-definitions/{pipeline_definition_id}/triggersList pipeline definition triggers

Parameters

Name	In	Required	Type
`project_id`	path	yes	string
`pipeline_definition_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Successful response.	`triggerList`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

POST/projects/{project_id}/pipeline-definitions/{pipeline_definition_id}/triggersCreate trigger

Parameters

Name	In	Required	Type
`project_id`	path	yes	string
`pipeline_definition_id`	path	yes	string

Request body

application/json — createTriggerRequest

Responses

Status	Description	Schema
`200`	Successful response.	`trigger`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

GET/projects/{project_id}/triggers/{trigger_id}Get trigger

Parameters

Name	In	Required	Type
`project_id`	path	yes	string
`trigger_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Successful response.	`trigger`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

PATCH/projects/{project_id}/triggers/{trigger_id}Update trigger

Parameters

Name	In	Required	Type
`project_id`	path	yes	string
`trigger_id`	path	yes	string

Request body

application/json — updateTriggerRequest

Responses

Status	Description	Schema
`200`	Successful response.	`trigger`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

DELETE/projects/{project_id}/triggers/{trigger_id}Delete trigger

Parameters

Name	In	Required	Type
`project_id`	path	yes	string
`trigger_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Successful response.	`triggerDeleted`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

Usage2

Endpoints related to organization usage exports. The Usage API is an API provided by CircleCI to __Restrictions__ * Max result set size of 100MB * Query timeout of 4 hours. * Max date window of 32 days * 13 months of historical data is available * No PII is surfaced in the Usage API (e.g. email * The POST endpoint can only be queried up to (i.e. * The GET endpoint can only be queried up to (i.e. * To increase performance the API can generate multiple __Requirements__ * organization ID - To get your organization ID * API Personal Access Token - https://circleci.com/docs/m __Report Fields__ | | Field |---------------------------------------|---------------- | | organization_id | | organization_name | | organization_created_date | Project-level attributes | project_id | | project_name | | project_created_date | | last_build_finished_at | Pipeline-level attributes | vcs_name | | vcs_url | | vcs_branch | | pipeline_id | | pipeline_created_at | | pipeline_number | | is_unregistered_user | | pipeline_trigger_source | | pipeline_trigger_user_id | Workflow-level attributes | workflow_id | | workflow_name | | workflow_first_job_queued_at | | workflow_first_ | | workflow_stopped_at | | is_workflow_successful | Job-level attributes | job_name | | job_id | | job_run_number | | job_run_date | | job_run_queued_at | | job_run_started_at | | job_run_stopped_at | | job_build_status | | resource_class | | operating_system | | executor | | parallelism | | job_run_seconds | | median_cpu_utilization_pct | | max_cpu_utilization_pct | | median_ram_utilization_pct | | max_ram_utilization_pct | Credit consumption metrics | compute_credits | | dlc_credits | | user_credits | | storage_credits | | network_credits | | lease_credits | | lease_overage_credits | | ipranges_credits | | total_credits customers to access all of their usage data on CircleCI. It contains all the metadata (org, project, pipeline, workflow, and job dimensions) as well as credit consumption data. It is provided at the near lowest level of granularity (at the job run level). address, Github login name) is rate limited to) 10 times per hour per org is rate limited to) 10 times per hour per org CSV files that need to be merged after download go to to Organization Settings tab in the CircleCI app. ie https://app.circleci.com/settings/organization/<vcs>/<org name>/overview anaging-api-tokens/ | Description | ---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | The org ID | | The org name | | The date (UTC) that the org was created | | The project ID / token | | The project name. For classic orgs, the project name is inherited from Github. For standalone, the org is set by the user. | | The date (UTC) that the project was created. For classic orgs, this is the date that the repo was authorized on CircleCI. For standalone orgs, this is the date that the project was created on CircleCI | | The date (UTC) of the last pipeline run on this project | | The name of the VCS connected to the project on which the pipeline was run | | The URL of the VCS on which the pipeline was run | | The branch on which the pipeline was run | | The ID of the pipeline instance that was triggered. If a pipeline is re-run, it will share the same pipeline ID as the original pipeline instance | | The date (UTC) the pipeline instance was first triggered | | The pipeline number | | Y/N flag of whether the pipeline was triggered by a CircleCI user or a user not registered on CircleCI. Examples of the latter include users who commit on a connected VCS and consume credits on CircleCI. | | The source of the pipeline instance trigger (API, webhook, etc.) | | The user ID / token of the user who triggered the pipeline | | The ID of the workflow instance that was triggered | | The name of the workflow | | The timestamp (UTC) of when the workflow instance started to queue | job_started_at | The timestamp (UTC) of when the workflow instance started to run | | The timestamp (UTC) of when the workflow instance stopped | | Y/N flag of whether all jobs in the workflow were successfully ran | | The name of the job (the name the customer sees in the UI) | | The ID of the job run instance that was triggered | | The number of the job run instance that was triggered | | The date (UTC) of the job run instance began | | The timestamp (UTC) of when the job started to queue | | The timestamp (UTC) of when the job started to run | | The timestamp (UTC) of when the job stopped | | The status of the job run instance | | The resource class of the job run instance | | The operating system of the job run instance | | The executor of the job run instance | | The parallelism of the job run instance | | The duration in seconds of the job run instance | | The median CPU utilization calculated over the course of the entire job run instance. CPU utilization is logged every 15 seconds. It will not be available for any jobs under 15 seconds and occasionally will not be available for jobs greater than 15 seconds. | | The max CPU utilization logged over the course of the entire job run instance. CPU utilization is logged every 15 seconds. It will not be available for any jobs under 15 seconds and occasionally will not be available for jobs greater than 15 seconds. | | The median RAM utilization calculated over the course of the entire job run instance. RAM utilization is logged every 15 seconds. It will not be available for any jobs under 15 seconds and occasionally will not be available for jobs greater than 15 seconds. | | The max RAM utilization logged over the course of the entire job run instance. RAM utilization is logged every 15 seconds. It will not be available for any jobs under 15 seconds and occasionally will not be available for jobs greater than 15 seconds. | | The compute credits consumed by this job run instance | | The docker-layer caching credits consumed by this job run instance | | The user credits consumed by this job run instance | | The storage credits consumed by this job run instance. Note: When an organization is below its allocated storage threshold, a job that uses storage will have 0 storage credits applied. The organization's included storage threshold can be found on the [CircleCI web app](https://app.circleci.com/home) by navigating to **Plan > Plan Usage**. | | The network credits consumed by this job run instance | | The lease credits consumed by this job run instance | | The lease overage credits consumed by this job run instance | | The IP ranges credits consumed by this job run instance | | The total credits consumed by this job run instance |

POST/organizations/{org_id}/usage_export_jobCreate a usage export

Parameters

Name	In	Required	Type
`org_id`	path	yes	string

Request body

application/json (required)

Responses

Status	Description	Schema
`201`	Usage export created successfully	`usage_export_job`
`400`	—	—
`401`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

GET/organizations/{org_id}/usage_export_job/{usage_export_job_id}Get a usage export

Parameters

Name	In	Required	Type
`org_id`	path	yes	string
`usage_export_job_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Usage export fetched successfully	`get_usage_export_job_status`
`400`	—	—
`401`	—	—
`404`	—	—
`429`	—	—
`500`	—	—

Webhook5

Endpoints related to creating and managing outbound webhooks.

GET/webhookList webhooks

Parameters

Name	In	Required	Type
`scope-id`	query	yes	string
`scope-type`	query	yes	string

Responses

Status	Description	Schema
`200`	A list of webhooks.	`webhookList`
`400`	—	—
`404`	—	—
`500`	—	—

POST/webhookCreate an outbound webhook

Request body

application/json — createWebhookRequest (required)

Responses

Status	Description	Schema
`201`	A webhook.	`webhook`
`400`	—	—
`404`	—	—
`500`	—	—

GET/webhook/{webhook_id}Get a webhook

Parameters

Name	In	Required	Type
`webhook_id`	path	yes	string

Responses

Status	Description	Schema
`200`	A webhook.	`webhook`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

PUT/webhook/{webhook_id}Update an outbound webhook

Parameters

Name	In	Required	Type
`webhook_id`	path	yes	string

Request body

application/json — updateWebhookRequest (required)

Responses

Status	Description	Schema
`200`	A webhook.	`webhook`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

DELETE/webhook/{webhook_id}Delete an outbound webhook

Parameters

Name	In	Required	Type
`webhook_id`	path	yes	string

Responses

Status	Description	Schema
`200`	A confirmation message.	`webhookDeleted`
`400`	—	—
`401`	—	—
`404`	—	—
`500`	—	—

Groups4

GET/organizations/{org_id}/groupsGroups in an organization

Parameters

Name	In	Required	Type
`org_id`	path	yes	string
`limit`	query	no	integer
`page-token`	query	no	string

Responses

Status	Description	Schema
`200`	Successfully get all the groups in an organization. Results are paginated.	`groups`
`403`	—	—
`404`	—	—
`500`	—	—

POST/organizations/{org_id}/groupsCreate Groups

Parameters

Name	In	Required	Type
`org_id`	path	yes	string

Request body

application/json (required)

Responses

Status	Description	Schema
`201`	Successful creation of a group.	`group`
`400`	—	—
`401`	—	—
`403`	—	—
`404`	—	—
`409`	—	—
`500`	—	—

GET/organizations/{org_id}/groups/{group_id}A group in an organization

Parameters

Name	In	Required	Type
`org_id`	path	yes	string
`group_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Successfully gets a group. Members not included.	`group`
`403`	—	—
`404`	—	—
`500`	—	—

DELETE/organizations/{org_id}/groups/{group_id}Delete a group

Parameters

Name	In	Required	Type
`org_id`	path	yes	string
`group_id`	path	yes	string

Responses

Status	Description	Schema
`200`	Successful deletion of a group.	—
`401`	—	—
`403`	—	—
`404`	—	—
`500`	—	—

Organization6

POST/organizationCreate a new organization

Request body

application/json

Responses

Status	Description	Schema
`201`	The newly created organization	—
`default`	Error response.	—

GET/organization/{org-slug-or-id}Get an organization

Parameters

Name	In	Required	Type
`org-slug-or-id`	path	yes	string

Responses

Status	Description	Schema
`200`	An organization object	—
`default`	Error response.	—

DELETE/organization/{org-slug-or-id}Delete an organization

Parameters

Name	In	Required	Type
`org-slug-or-id`	path	yes	string

Responses

Status	Description	Schema
`202`	A confirmation message.	—
`default`	Error response.	—

GET/organization/{org-slug-or-id}/url-orb-allow-listList the entries in the org's URL Orb allow-list

Parameters

Name	In	Required	Type
`org-slug-or-id`	path	yes	string

Responses

Status	Description	Schema
`200`	URL Orb allow-list entries	—
`default`	Error response.	—

POST/organization/{org-slug-or-id}/url-orb-allow-listCreate a new URL Orb allow-list entry

Parameters

Name	In	Required	Type
`org-slug-or-id`	path	yes	string

Request body

application/json

Responses

Status	Description	Schema
`200`	The ID of the new URL Orb allow-list entry	—
`default`	Error response.	—

DELETE/organization/{org-slug-or-id}/url-orb-allow-list/{allow-list-entry-id}Remove an entry from the org's URL orb allow-list

Parameters

Name	In	Required	Type
`org-slug-or-id`	path	yes	string
`allow-list-entry-id`	path	yes	string

Responses

Status	Description	Schema
`200`	The ID of the removed URL Orb allow-list entry	—
`default`	Error response.	—

Schedule5

GET/project/{project-slug}/scheduleList schedule triggers

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string
`page-token`	query	no	string

Responses

Status	Description	Schema
`200`	A sequence of schedules.	—
`default`	Error response.	—

POST/project/{project-slug}/scheduleCreate a schedule

Parameters

Name	In	Required	Type
`project-slug`	path	yes	string

Request body

application/json

Responses

Status	Description	Schema
`201`	A schedule object.	—
`default`	Error response.	—

GET/schedule/{schedule-id}Get a schedule by ID. Available only on schedules associated with GitHub OAuth or Bitbucket Cloud pipeline definitions.

Parameters

Name	In	Required	Type
`schedule-id`	path	yes	string

Responses

Status	Description	Schema
`200`	A schedule object.	—
`default`	Error response.	—

PATCH/schedule/{schedule-id}Update a schedule

Parameters

Name	In	Required	Type
`schedule-id`	path	yes	string

Request body

application/json

Responses

Status	Description	Schema
`200`	A schedule object.	—
`default`	Error response.	—

DELETE/schedule/{schedule-id}Delete a schedule

Parameters

Name	In	Required	Type
`schedule-id`	path	yes	string

Responses

Status	Description	Schema
`200`	A confirmation message.	—
`default`	Error response.	—

Try it

Operation

API key

Developer reference

Base URLhttps://circleci.com/api/v2

Rate limit

CircleCI's API developer guide states it 'reserves the right to throttle the requests made by an individual user or to individual resources' to protect system stability, with different protections for different parts of the API — especially against sudden traffic bursts and sustained high-volume polling such as frequent status checks. A throttled request returns HTTP 429, usually accompanied by a Retry-After header giving the number of seconds to wait before retrying; CircleCI recommends handling this gracefully with exponential backoff rather than assuming a fixed per-endpoint quota.

Key endpoints

GET/me
GET/project/{project-slug}
POST/project/{project-slug}/pipeline
GET/project/{project-slug}/pipeline
GET/workflow/{id}/job

Changelog

Spec versionv2

Tracked paths76

Sep 2026content changed
Sep 2026content changed

Tracking since Sep 2026. See every tracked change ↗ ·Subscribe with RSS ↗

Featured in

1 collection

Spec-backed APIs

GreatAPIs Score

Embed this badge

Auth quickstart

Endpoints

Try it

Developer reference

Changelog

Featured in

People comparing CircleCI also look at…

CircleCI vs Azure DevOps Health

CircleCI vs Travis CI

CircleCI vs Bitrise

CircleCI vs Buddy