# CircleCI API

> This describes the resources that make up the CircleCI API v2.

## Special Instructions

- Base URL: `https://circleci.com/api/v2`
- Authentication: send a personal API token in the `Circle-Token` header. Generate one at <https://app.circleci.com/settings/user/tokens>.
- `project_id` parameters are UUIDs (not the `gh/org/repo` slug used by older endpoints).
- Rate limiting: 5000 requests per hour per token.
- The full OpenAPI spec is at <https://circleci.com/docs/api/v2/openapi.json>.
- Each operation below links to a per-endpoint Markdown file at `/api/v2/operations/{operationId}.md`. The same `operationId` corresponds to the `#operation/{operationId}` fragment on the rendered docs page.
- HTML documentation for humans: <https://circleci.com/docs/api/v2/>.

## Context

- [List contexts](/api/v2/operations/listContexts.md): `GET /context`
- [Create a new context](/api/v2/operations/createContext.md): `POST /context`
- [Get a context](/api/v2/operations/getContext.md): `GET /context/{context_id}`
- [Delete a context](/api/v2/operations/deleteContext.md): `DELETE /context/{context_id}`
- [List environment variables](/api/v2/operations/listEnvironmentVariablesFromContext.md): `GET /context/{context_id}/environment-variable`
- [Add or update an environment variable](/api/v2/operations/addEnvironmentVariableToContext.md): `PUT /context/{context_id}/environment-variable/{env_var_name}`
- [Remove an environment variable](/api/v2/operations/deleteEnvironmentVariableFromContext.md): `DELETE /context/{context_id}/environment-variable/{env_var_name}`
- [Get context restrictions](/api/v2/operations/getContextRestrictions.md): `GET /context/{context_id}/restrictions`
- [Create context restriction](/api/v2/operations/createContextRestriction.md): `POST /context/{context_id}/restrictions`
- [Delete context restriction](/api/v2/operations/deleteContextRestriction.md): `DELETE /context/{context_id}/restrictions/{restriction_id}`

## Insights

- [Get summary metrics and trends for a project across it's workflows and branches](/api/v2/operations/getProjectWorkflowsPageData.md): `GET /insights/pages/{project-slug}/summary`
- [Job timeseries data](/api/v2/operations/getJobTimeseries.md): `GET /insights/time-series/{project-slug}/workflows/{workflow-name}/jobs`
- [Get summary metrics with trends for the entire org, and for each project.](/api/v2/operations/getOrgSummaryData.md): `GET /insights/{org-slug}/summary`
- [Get all branches for a project](/api/v2/operations/getAllInsightsBranches.md): `GET /insights/{project-slug}/branches`
- [Get flaky tests for a project](/api/v2/operations/getFlakyTests.md): `GET /insights/{project-slug}/flaky-tests`
- [Get summary metrics for a project's workflows](/api/v2/operations/getProjectWorkflowMetrics.md): `GET /insights/{project-slug}/workflows`
- [Get recent runs of a workflow](/api/v2/operations/getProjectWorkflowRuns.md): `GET /insights/{project-slug}/workflows/{workflow-name}`
- [Get summary metrics for a project workflow's jobs.](/api/v2/operations/getProjectWorkflowJobMetrics.md): `GET /insights/{project-slug}/workflows/{workflow-name}/jobs`
- [Get metrics and trends for workflows](/api/v2/operations/getWorkflowSummary.md): `GET /insights/{project-slug}/workflows/{workflow-name}/summary`
- [Get test metrics for a project's workflows](/api/v2/operations/getProjectWorkflowTestMetrics.md): `GET /insights/{project-slug}/workflows/{workflow-name}/test-metrics`

## User

- [User Information](/api/v2/operations/getCurrentUser.md): `GET /me`
- [Collaborations](/api/v2/operations/getCollaborations.md): `GET /me/collaborations`
- [User Information](/api/v2/operations/getUser.md): `GET /user/{id}`

## Pipeline

- [Get a list of pipelines](/api/v2/operations/listPipelines.md): `GET /pipeline`
- [Continue a pipeline](/api/v2/operations/continuePipeline.md): `POST /pipeline/continue`
- [Get a pipeline by ID](/api/v2/operations/getPipelineById.md): `GET /pipeline/{pipeline-id}`
- [Get a pipeline's configuration](/api/v2/operations/getPipelineConfigById.md): `GET /pipeline/{pipeline-id}/config`
- [Get a pipeline's workflows](/api/v2/operations/listWorkflowsByPipelineId.md): `GET /pipeline/{pipeline-id}/workflow`
- [Get pipeline values for a pipeline](/api/v2/operations/getPipelineValuesById.md): `GET /pipeline/{pipeline_id}/values`
- [Get all pipelines](/api/v2/operations/listPipelinesForProject.md): `GET /project/{project-slug}/pipeline`
- [Trigger a new pipeline](/api/v2/operations/triggerPipeline.md): `POST /project/{project-slug}/pipeline`
- [Get your pipelines](/api/v2/operations/listMyPipelines.md): `GET /project/{project-slug}/pipeline/mine`
- [Get a pipeline by pipeline number](/api/v2/operations/getPipelineByNumber.md): `GET /project/{project-slug}/pipeline/{pipeline-number}`
- [[Recommended] Trigger a new pipeline](/api/v2/operations/triggerPipelineRun.md): `POST /project/{provider}/{organization}/{project}/pipeline/run`

## Job

- [Cancel job by job ID](/api/v2/operations/cancelJobByJobID.md): `POST /jobs/{job-id}/cancel`
- [Get a job](/api/v2/operations/getJob.md): `GET /jobs/{job_id}`
- [Get job details](/api/v2/operations/getJobDetails.md): `GET /project/{project-slug}/job/{job-number}`
- [Cancel job by job number](/api/v2/operations/cancelJobByJobNumber.md): `POST /project/{project-slug}/job/{job-number}/cancel`
- [Get a job's artifacts](/api/v2/operations/getJobArtifacts.md): `GET /project/{project-slug}/{job-number}/artifacts`
- [Get test metadata](/api/v2/operations/getTests.md): `GET /project/{project-slug}/{job-number}/tests`

## Workflow

- [Get a workflow](/api/v2/operations/getWorkflowById.md): `GET /workflow/{id}`
- [Approve a job](/api/v2/operations/approvePendingApprovalJobById.md): `POST /workflow/{id}/approve/{approval_request_id}`
- [Cancel a workflow](/api/v2/operations/cancelWorkflow.md): `POST /workflow/{id}/cancel`
- [Get a workflow's jobs](/api/v2/operations/listWorkflowJobs.md): `GET /workflow/{id}/job`
- [Rerun a workflow](/api/v2/operations/rerunWorkflow.md): `POST /workflow/{id}/rerun`

## Webhook

- [List webhooks](/api/v2/operations/getWebhooks.md): `GET /webhook`
- [Create an outbound webhook](/api/v2/operations/createWebhook.md): `POST /webhook`
- [Get a webhook](/api/v2/operations/getWebhookById.md): `GET /webhook/{webhook-id}`
- [Update an outbound webhook](/api/v2/operations/updateWebhook.md): `PUT /webhook/{webhook-id}`
- [Delete an outbound webhook](/api/v2/operations/deleteWebhook.md): `DELETE /webhook/{webhook-id}`

## OIDC Token Management

- [Get org-level claims](/api/v2/operations/GetOrgClaims.md): `GET /org/{orgID}/oidc-custom-claims`
- [Patch org-level claims](/api/v2/operations/PatchOrgClaims.md): `PATCH /org/{orgID}/oidc-custom-claims`
- [Delete org-level claims](/api/v2/operations/DeleteOrgClaims.md): `DELETE /org/{orgID}/oidc-custom-claims`
- [Get project-level claims](/api/v2/operations/GetProjectClaims.md): `GET /org/{orgID}/project/{projectID}/oidc-custom-claims`
- [Patch project-level claims](/api/v2/operations/PatchProjectClaims.md): `PATCH /org/{orgID}/project/{projectID}/oidc-custom-claims`
- [Delete project-level claims](/api/v2/operations/DeleteProjectClaims.md): `DELETE /org/{orgID}/project/{projectID}/oidc-custom-claims`

## Policy Management

- [Retrieves the owner's decision audit logs.](/api/v2/operations/GetDecisionLogs.md): `GET /owner/{ownerID}/context/{context}/decision`
- [Makes a decision](/api/v2/operations/MakeDecision.md): `POST /owner/{ownerID}/context/{context}/decision`
- [Get the decision settings](/api/v2/operations/GetDecisionSettings.md): `GET /owner/{ownerID}/context/{context}/decision/settings`
- [Set the decision settings](/api/v2/operations/SetDecisionSettings.md): `PATCH /owner/{ownerID}/context/{context}/decision/settings`
- [Retrieves the owner's decision audit log by given decisionID](/api/v2/operations/GetDecisionLog.md): `GET /owner/{ownerID}/context/{context}/decision/{decisionID}`
- [Retrieves Policy Bundle for a given decision log ID](/api/v2/operations/GetDecisionLogPolicyBundle.md): `GET /owner/{ownerID}/context/{context}/decision/{decisionID}/policy-bundle`
- [Retrieves Policy Bundle](/api/v2/operations/GetPolicyBundle.md): `GET /owner/{ownerID}/context/{context}/policy-bundle`
- [Creates policy bundle for the context](/api/v2/operations/CreatePolicyBundle.md): `POST /owner/{ownerID}/context/{context}/policy-bundle`
- [Retrieves a policy document](/api/v2/operations/GetPolicyDocument.md): `GET /owner/{ownerID}/context/{context}/policy-bundle/{policyName}`

## Deploy

- [List Components](/api/v2/operations/listComponents.md): `GET /deploy/components`
- [Get Component](/api/v2/operations/getComponent.md): `GET /deploy/components/{component_id}`
- [List Component Versions](/api/v2/operations/listComponentVersions.md): `GET /deploy/components/{component_id}/versions`
- [List Environments](/api/v2/operations/listEnvironments.md): `GET /deploy/environments`
- [Get Environment](/api/v2/operations/getEnvironment.md): `GET /deploy/environments/{environment_id}`

## OTel

- [🧪 List OTLP exporters](/api/v2/operations/listOtelExporters.md): `GET /otel/exporters`
- [🧪 Create an OTLP exporter](/api/v2/operations/createOtelExporter.md): `POST /otel/exporters`
- [🧪 Delete an OTLP exporter](/api/v2/operations/deleteOtelExporter.md): `DELETE /otel/exporters/{otel_exporter_id}`

## Pipeline Definition

- [List pipeline definitions](/api/v2/operations/listPipelineDefinitions.md): `GET /projects/{project_id}/pipeline-definitions`
- [Create pipeline definition](/api/v2/operations/createPipelineDefinition.md): `POST /projects/{project_id}/pipeline-definitions`
- [Get pipeline definition](/api/v2/operations/getPipelineDefinition.md): `GET /projects/{project_id}/pipeline-definitions/{pipeline_definition_id}`
- [Update pipeline definition](/api/v2/operations/updatePipelineDefinition.md): `PATCH /projects/{project_id}/pipeline-definitions/{pipeline_definition_id}`
- [Delete pipeline definition](/api/v2/operations/deletePipelineDefinition.md): `DELETE /projects/{project_id}/pipeline-definitions/{pipeline_definition_id}`

## Project

- [Create a new project](/api/v2/operations/createProject.md): `POST /organization/{org-slug-or-id}/project`
- [Get a project](/api/v2/operations/getProjectBySlug.md): `GET /project/{project-slug}`
- [Delete a project](/api/v2/operations/deleteProjectBySlug.md): `DELETE /project/{project-slug}`
- [Get all checkout keys](/api/v2/operations/listCheckoutKeys.md): `GET /project/{project-slug}/checkout-key`
- [Create a new checkout key](/api/v2/operations/createCheckoutKey.md): `POST /project/{project-slug}/checkout-key`
- [Get a checkout key](/api/v2/operations/getCheckoutKey.md): `GET /project/{project-slug}/checkout-key/{fingerprint}`
- [Delete a checkout key](/api/v2/operations/deleteCheckoutKey.md): `DELETE /project/{project-slug}/checkout-key/{fingerprint}`
- [List all environment variables](/api/v2/operations/listEnvVars.md): `GET /project/{project-slug}/envvar`
- [Create an environment variable](/api/v2/operations/createEnvVar.md): `POST /project/{project-slug}/envvar`
- [Get a masked environment variable](/api/v2/operations/getEnvVar.md): `GET /project/{project-slug}/envvar/{name}`
- [Delete an environment variable](/api/v2/operations/deleteEnvVar.md): `DELETE /project/{project-slug}/envvar/{name}`
- [Get project settings](/api/v2/operations/getProjectSettings.md): `GET /project/{provider}/{organization}/{project}/settings`
- [Update project settings](/api/v2/operations/patchProjectSettings.md): `PATCH /project/{provider}/{organization}/{project}/settings`

## Rollback

- [Rollback a project](/api/v2/operations/rollbackProject.md): `POST /projects/{project_id}/rollback`

## Trigger

- [List pipeline definition triggers](/api/v2/operations/listPipelineDefinitionTriggers.md): `GET /projects/{project_id}/pipeline-definitions/{pipeline_definition_id}/triggers`
- [Create trigger](/api/v2/operations/createTrigger.md): `POST /projects/{project_id}/pipeline-definitions/{pipeline_definition_id}/triggers`
- [Get trigger](/api/v2/operations/getTrigger.md): `GET /projects/{project_id}/triggers/{trigger_id}`
- [Update trigger](/api/v2/operations/updateTrigger.md): `PATCH /projects/{project_id}/triggers/{trigger_id}`
- [Delete trigger](/api/v2/operations/deleteTrigger.md): `DELETE /projects/{project_id}/triggers/{trigger_id}`

## Usage

- [Create a usage export](/api/v2/operations/createUsageExport.md): `POST /organizations/{org_id}/usage_export_job`
- [Get a usage export](/api/v2/operations/getUsageExport.md): `GET /organizations/{org_id}/usage_export_job/{usage_export_job_id}`

## Groups

- [Groups in an organization](/api/v2/operations/getOrganizationGroups.md): `GET /organizations/{org_id}/groups`
- [Create Groups](/api/v2/operations/createOrganizationGroup.md): `POST /organizations/{org_id}/groups`
- [A group in an organization](/api/v2/operations/getGroup.md): `GET /organizations/{org_id}/groups/{group_id}`
- [Delete a group](/api/v2/operations/deleteGroup.md): `DELETE /organizations/{org_id}/groups/{group_id}`

## Organization

- [Create a new organization](/api/v2/operations/createOrganization.md): `POST /organization`
- [Get an organization](/api/v2/operations/getOrganization.md): `GET /organization/{org-slug-or-id}`
- [Delete an organization](/api/v2/operations/deleteOrganization.md): `DELETE /organization/{org-slug-or-id}`
- [List the entries in the org's URL Orb allow-list](/api/v2/operations/listURLOrbAllowListEntries.md): `GET /organization/{org-slug-or-id}/url-orb-allow-list`
- [Create a new URL Orb allow-list entry](/api/v2/operations/createURLOrbAllowListEntry.md): `POST /organization/{org-slug-or-id}/url-orb-allow-list`
- [Remove an entry from the org's URL orb allow-list](/api/v2/operations/removeURLOrbAllowListEntry.md): `DELETE /organization/{org-slug-or-id}/url-orb-allow-list/{allow-list-entry-id}`

## Schedule

- [List schedule triggers](/api/v2/operations/listSchedulesForProject.md): `GET /project/{project-slug}/schedule`
- [Create a schedule](/api/v2/operations/createSchedule.md): `POST /project/{project-slug}/schedule`
- [Get a schedule by ID. Available only on schedules associated with GitHub OAuth or Bitbucket Cloud pipeline definitions.](/api/v2/operations/getScheduleById.md): `GET /schedule/{schedule-id}`
- [Update a schedule](/api/v2/operations/updateSchedule.md): `PATCH /schedule/{schedule-id}`
- [Delete a schedule](/api/v2/operations/deleteScheduleById.md): `DELETE /schedule/{schedule-id}`