API docs by Redocly

CircleCI API (v2)

Download OpenAPI specification:

URL: https://support.circleci.com License: MIT

This document outlines the endpoints and resources that are a part of the CircleCI API v2.

Context

[EXPERIMENTAL] Endpoints related to managing a context.

Get context restrictions

Gets a list of project and expression restrictions associated with a context.

Authorizations:
api_key_headerbasic_auth
path Parameters
context_id
required
string
Example: be8bb2e3-c3d6-4098-89f4-572ff976ba9a

An opaque identifier of a context.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_page_token": "string"
}

Create context restriction

Creates project or expression restriction on a context.

Authorizations:
api_key_headerbasic_auth
path Parameters
context_id
required
string
Example: be8bb2e3-c3d6-4098-89f4-572ff976ba9a

An opaque identifier of a context.

Request Body schema: application/json
required
project_id
string <uuid>
Deprecated

Deprecated - Use "restriction_type" and "restriction_value" instead.

The project ID to use for a project restriction. This is mutually exclusive with restriction_type and restriction_value and implies restriction_type is "project".

restriction_type
string
Enum: "project" "expression"

Type of the restriction.

restriction_value
string

Value used to evaluate the restriction. If the restriction_type is project, this will be the project UUID. If the restriction_type is expression, this will be the expression rule.

Responses

Request samples

Content type
application/json
Example
{
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  • "restriction_type": "project",
  • "restriction_value": "405d8375-3514-403b-8c43-83ae74cfe0e9"
}

Response samples

Content type
application/json
Example
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  • "name": "project-name",
  • "restriction_type": "project",
  • "restriction_value": "405d8375-3514-403b-8c43-83ae74cfe0e9"
}

Delete context restriction

Deletes a project or expression restriction on a context.

Authorizations:
api_key_headerbasic_auth
path Parameters
context_id
required
string
Example: be8bb2e3-c3d6-4098-89f4-572ff976ba9a

An opaque identifier of a context.

restriction_id
required
string
Example: 1c23d2cb-07b1-4a28-8af3-e369732050ed

An opaque identifier of a context restriction.

Responses

Response samples

Content type
application/json
{
  • "message": "Context restriction deleted."
}

Pipeline

Endpoints relating to pipelines. Get information about your pipelines. Trigger or continue a pipeline.

[Recommended] Trigger a new pipeline

Trigger a pipeline given a pipeline definition ID. Supports all integrations except GitLab.

The slash-separated project slug is shown in Project Settings > Overview.

Depending on the organization type, the project slug may have a human-readable format (vcs_type/org_name/project_name) or be an opaque string (e.g. circleci/43G3lM5RtfFE7v5sa4nWAU/44n9wujWcTnVZ2b5S8Fnat).

Authorizations:
api_key_headerbasic_auth
path Parameters
provider
required
string
Enum: "github" "gh" "bitbucket" "bb" "circleci"
Example: gh

The first segment of the slash-separated project slug, as shown in Project Settings > Overview.

organization
required
string
Example: CircleCI-Public

The second segment of the slash-separated project slug, as shown in Project Settings > Overview. Depending on the organization type, this may be the org name (e.g. my-org) or an ID (e.g. 43G3lM5RtfFE7v5sa4nWAU).

project
required
string
Example: api-preview-docs

The third segment of the slash-separated project slug, as shown in Project Settings > Overview. Depending on the organization type, this may be the project name (e.g. my-project) or an ID (e.g. 44n9wujWcTnVZ2b5S8Fnat).

Request Body schema: application/json
definition_id
string <uuid>

The unique id for the pipeline definition. This can be found in the page Project Settings > Pipelines.

object
object
object

An object containing pipeline parameters and their values. Pipeline parameters have the following size limits: 100 max entries, 128 maximum key length, 512 maximum value length.

Responses

Request samples

Content type
application/json
{
  • "definition_id": "2338d0ae-5541-4bbf-88a2-55e9f7281f80",
  • "config": {
    },
  • "checkout": {
    },
  • "parameters": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Ignoring pipeline due to CI skip in the commit"
}

Pipeline Definition

Endpoints related to creating and managing pipeline definitions.

List pipeline definitions

List all pipeline definitions for a given project. Share feedback about our Project Administration APIs.

Authorizations:
api_key_headerbasic_auth
path Parameters
project_id
required
string
Example: 39723015-b399-4601-9ff6-bd1bfbed8fa8

An opaque identifier of a project.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create pipeline definition

Create a pipeline definition for a given project. Currently only supported for pipeline definitions where config_source.provider is github_app. Share feedback about our Project Administration APIs.

Authorizations:
api_key_headerbasic_auth
path Parameters
project_id
required
string
Example: 39723015-b399-4601-9ff6-bd1bfbed8fa8

An opaque identifier of a project.

Request Body schema: application/json
name
required
string

The name of the pipeline definition.

description
string

The description of the pipeline definition.

required
object or object
required
object

The resource to be used when running the checkout command.

Responses

Request samples

Content type
application/json
{
  • "name": "Some pipeline name",
  • "description": "Some pipeline description",
  • "config_source": {
    },
  • "checkout_source": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "some pipeline",
  • "description": "some pipeline description",
  • "created_at": "2019-08-24T14:15:22Z",
  • "config_source": {
    },
  • "checkout_source": {
    }
}

Get pipeline definition

Get details for a pipeline definition. Currently only supported for pipeline definitions where config_source.provider is github_app or bitbucket_dc. Share feedback about our Project Administration APIs.

Authorizations:
api_key_headerbasic_auth
path Parameters
project_id
required
string
Example: 39723015-b399-4601-9ff6-bd1bfbed8fa8

An opaque identifier of a project.

pipeline_definition_id
required
string
Example: 6cb29b00-8e02-4357-8bc0-313983bf1f46

An opaque identifier of a pipeline definition.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "some pipeline",
  • "description": "some pipeline description",
  • "created_at": "2019-08-24T14:15:22Z",
  • "config_source": {
    },
  • "checkout_source": {
    }
}

Update pipeline definition

Update pipeline definition. Currently only supported for pipeline definitions where config_source.provider is github_app or bitbucket_dc. Share feedback about our Project Administration APIs.

Authorizations:
api_key_headerbasic_auth
path Parameters
project_id
required
string
Example: 39723015-b399-4601-9ff6-bd1bfbed8fa8

An opaque identifier of a project.

pipeline_definition_id
required
string
Example: 6cb29b00-8e02-4357-8bc0-313983bf1f46

An opaque identifier of a pipeline definition.

Request Body schema: application/json
name
string

The name of the pipeline definition.

description
string

The description of the pipeline definition.

object

The resource that stores the CircleCI config YAML used for this pipeline definition.

object

The resource to be used when running the checkout command.

Responses

Request samples

Content type
application/json
{
  • "name": "Some pipeline name",
  • "description": "Some pipeline description",
  • "config_source": {
    },
  • "checkout_source": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "some pipeline",
  • "description": "some pipeline description",
  • "created_at": "2019-08-24T14:15:22Z",
  • "config_source": {
    },
  • "checkout_source": {
    }
}

Delete pipeline definition

Delete pipeline definition. Currently only supported for pipeline definitions where config_source.provider is github_app or bitbucket_dc. Share feedback about our Project Administration APIs.

Authorizations:
api_key_headerbasic_auth
path Parameters
project_id
required
string
Example: 39723015-b399-4601-9ff6-bd1bfbed8fa8

An opaque identifier of a project.

pipeline_definition_id
required
string
Example: 6cb29b00-8e02-4357-8bc0-313983bf1f46

An opaque identifier of a pipeline definition.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Project

[EXPERIMENTAL] Endpoints related to creating and managing a project.

⚠️ Create a project

[DEPRECATED] This endpoint is replaced by organization/{org-slug-or-id}/project and documentation will be removed on August 1st, 2025. Creates a new CircleCI project, and returns a list of the default advanced settings. Can only be called on a repo with a main branch and an existing config.yml file. Not yet available to projects that use GitLab or GitHub App.

Authorizations:
api_key_headerbasic_auth
path Parameters
provider
required
string
Enum: "github" "gh" "bitbucket" "bb" "circleci"
Example: gh

The first segment of the slash-separated project slug, as shown in Project Settings > Overview.

organization
required
string
Example: CircleCI-Public

The second segment of the slash-separated project slug, as shown in Project Settings > Overview. Depending on the organization type, this may be the org name (e.g. my-org) or an ID (e.g. 43G3lM5RtfFE7v5sa4nWAU).

project
required
string
Example: api-preview-docs

The third segment of the slash-separated project slug, as shown in Project Settings > Overview. Depending on the organization type, this may be the project name (e.g. my-project) or an ID (e.g. 44n9wujWcTnVZ2b5S8Fnat).

Responses

Response samples

Content type
application/json
{
  • "advanced": {
    }
}

🧪 Get project settings

[EXPERIMENTAL] Returns a list of the advanced settings for a CircleCI project, whether enabled (true) or not (false).

Authorizations:
api_key_headerbasic_auth
path Parameters
provider
required
string
Enum: "github" "gh" "bitbucket" "bb" "circleci"
Example: gh

The first segment of the slash-separated project slug, as shown in Project Settings > Overview.

organization
required
string
Example: CircleCI-Public

The second segment of the slash-separated project slug, as shown in Project Settings > Overview. Depending on the organization type, this may be the org name (e.g. my-org) or an ID (e.g. 43G3lM5RtfFE7v5sa4nWAU).

project
required
string
Example: api-preview-docs

The third segment of the slash-separated project slug, as shown in Project Settings > Overview. Depending on the organization type, this may be the project name (e.g. my-project) or an ID (e.g. 44n9wujWcTnVZ2b5S8Fnat).

Responses

Response samples

Content type
application/json
{
  • "advanced": {
    }
}

🧪 Update project settings

[EXPERIMENTAL] Updates one or more of the advanced settings for a CircleCI project.

Authorizations:
api_key_headerbasic_auth
path Parameters
provider
required
string
Enum: "github" "gh" "bitbucket" "bb" "circleci"
Example: gh

The first segment of the slash-separated project slug, as shown in Project Settings > Overview.

organization
required
string
Example: CircleCI-Public

The second segment of the slash-separated project slug, as shown in Project Settings > Overview. Depending on the organization type, this may be the org name (e.g. my-org) or an ID (e.g. 43G3lM5RtfFE7v5sa4nWAU).

project
required
string
Example: api-preview-docs

The third segment of the slash-separated project slug, as shown in Project Settings > Overview. Depending on the organization type, this may be the project name (e.g. my-project) or an ID (e.g. 44n9wujWcTnVZ2b5S8Fnat).

Request Body schema: application/json
required

The setting(s) to update, including one or more fields in the JSON object. Note that oss: true will only be set on projects whose underlying repositories are actually open source.

object

Responses

Request samples

Content type
application/json
{
  • "advanced": {
    }
}

Response samples

Content type
application/json
{
  • "advanced": {
    }
}

Trigger

Endpoints related to creating and managing triggers.

List pipeline definition triggers

List all triggers for a given pipeline definition. Currently only supported for pipeline definitions where config_source.provider is github_app or bitbucket_dc. Share feedback about our Project Administration APIs.

Authorizations:
api_key_headerbasic_auth
path Parameters
project_id
required
string
Example: 39723015-b399-4601-9ff6-bd1bfbed8fa8

An opaque identifier of a project.

pipeline_definition_id
required
string
Example: 6cb29b00-8e02-4357-8bc0-313983bf1f46

An opaque identifier of a pipeline definition.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create trigger

Create a trigger for a given pipeline definition. Currently only supported for pipeline definitions where config_source.provider is github_app. Share feedback about our Project Administration APIs.

Authorizations:
api_key_headerbasic_auth
path Parameters
project_id
required
string
Example: 39723015-b399-4601-9ff6-bd1bfbed8fa8

An opaque identifier of a project.

pipeline_definition_id
required
string
Example: 6cb29b00-8e02-4357-8bc0-313983bf1f46

An opaque identifier of a pipeline definition.

Request Body schema: application/json
required
object

The source of events to use for this trigger. The repo object must be specified when provider is github_app, and the webhook object may only be specified when provider is webhook.

event_preset
string
Enum: "all-pushes" "only-tags" "default-branch-pushes" "only-build-prs" "only-open-prs" "only-labeled-prs" "only-merged-prs" "only-ready-for-review-prs" "only-branch-delete" "only-build-pushes-to-non-draft-prs"

The name of the event preset to use when filtering events for this trigger. Only applicable when event_source.provider is github_app.

checkout_ref
string

The ref to use when checking out code for pipeline runs created from this trigger. Always required when event_source.provider is webhook. When event_source.provider is github_app, only expected if the event source repository (identified by event_source.provider.repo.external_id) is different to the checkout source repository of the associated Pipeline Definition. Otherwise, must be omitted.

config_ref
string

The ref to use when fetching config for pipeline runs created from this trigger. Always required when event_source.provider is webhook. When event_source.provider is github_app, only expected if the event source repository (identified by event_source.provider.repo.external_id) is different to the config source repository of the associated Pipeline Definition. Otherwise, must be omitted.

event_name
string

The name of the triggering event. This should only be set for triggers where provider is webhook.

Responses

Request samples

Content type
application/json
{
  • "event_source": {
    },
  • "event_preset": "all-pushes",
  • "checkout_ref": "some-checkout-ref",
  • "config_ref": "some-config-ref",
  • "event_name": "some-event-name"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "event_name": "some event name",
  • "created_at": "2019-08-24T14:15:22Z",
  • "event_source": {},
  • "event_preset": "all-pushes",
  • "checkout_ref": "some-checkout-ref",
  • "config_ref": "some-config-ref"
}

Get trigger

Get details for a trigger. Currently only supported for triggers where event_source.provider is github_app, bitbucket_dc or webhook. Share feedback about our Project Administration APIs. Breaking change upcoming on May 27, 2025.

Authorizations:
api_key_headerbasic_auth
path Parameters
project_id
required
string
Example: 39723015-b399-4601-9ff6-bd1bfbed8fa8

An opaque identifier of a project.

trigger_id
required
string
Example: bbea3a3d-4686-48b6-8d2d-2a14ace3913c

An opaque identifier of a trigger.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "event_name": "some event name",
  • "created_at": "2019-08-24T14:15:22Z",
  • "event_source": {},
  • "event_preset": "all-pushes",
  • "checkout_ref": "some-checkout-ref",
  • "config_ref": "some-config-ref"
}

Update trigger

Update a trigger. Currently only supported for triggers where event_source.provider is github_app, bitbucket_dc or webhook. Share feedback about our Project Administration APIs.

Authorizations:
api_key_headerbasic_auth
path Parameters
project_id
required
string
Example: 39723015-b399-4601-9ff6-bd1bfbed8fa8

An opaque identifier of a project.

trigger_id
required
string
Example: bbea3a3d-4686-48b6-8d2d-2a14ace3913c

An opaque identifier of a trigger.

Request Body schema: application/json
event_preset
string
Enum: "all-pushes" "only-tags" "default-branch-pushes" "only-build-prs" "only-open-prs" "only-labeled-prs" "only-merged-prs" "only-ready-for-review-prs" "only-branch-delete" "only-build-pushes-to-non-draft-prs"

The name of the event preset to use when filtering events for this trigger. Only applicable when event_source.provider is github_app.

checkout_ref
string

The ref to use when checking out code for pipeline runs created from this trigger.

config_ref
string

The ref to use when fetching config for pipeline runs created from this trigger.

event_name
string

The name of the triggering event. This can only be set for triggers where provider is webhook.

object

Responses

Request samples

Content type
application/json
{
  • "event_preset": "all-pushes",
  • "checkout_ref": "some-checkout-ref",
  • "config_ref": "some-config-ref",
  • "event_name": "some event name",
  • "event_source": {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "event_name": "some event name",
  • "created_at": "2019-08-24T14:15:22Z",
  • "event_source": {},
  • "event_preset": "all-pushes",
  • "checkout_ref": "some-checkout-ref",
  • "config_ref": "some-config-ref"
}

Delete trigger

Delete a trigger. Currently only supported for triggers where event_source.provider is github_app, bitbucket_dc or webhook. Share feedback about our Project Administration APIs.

Authorizations:
api_key_headerbasic_auth
path Parameters
project_id
required
string
Example: 39723015-b399-4601-9ff6-bd1bfbed8fa8

An opaque identifier of a project.

trigger_id
required
string
Example: bbea3a3d-4686-48b6-8d2d-2a14ace3913c

An opaque identifier of a trigger.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Usage

Endpoints related to organization usage exports.

The Usage API is an API provided by CircleCI to 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).

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 address, Github login name)
  • The POST endpoint can only be queried up to (i.e. is rate limited to) 10 times per hour per org
  • The GET endpoint can only be queried up to (i.e. is rate limited to) 10 times per hour per org
  • To increase performance the API can generate multiple CSV files that need to be merged after download

Requirements

Report Fields

Field Description
organization_id The org ID
organization_name The org name
organization_created_date The date (UTC) that the org was created
Project-level attributes project_id The project ID / token
project_name The project name. For classic orgs, the project name is inherited from Github. For standalone, the org is set by the user.
project_created_date 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
last_build_finished_at The date (UTC) of the last pipeline run on this project
Pipeline-level attributes vcs_name The name of the VCS connected to the project on which the pipeline was run
vcs_url The URL of the VCS on which the pipeline was run
vcs_branch The branch on which the pipeline was run
pipeline_id 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
pipeline_created_at The date (UTC) the pipeline instance was first triggered
pipeline_number The pipeline number
is_unregistered_user 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.
pipeline_trigger_source The source of the pipeline instance trigger (API, webhook, etc.)
pipeline_trigger_user_id The user ID / token of the user who triggered the pipeline
Workflow-level attributes workflow_id The ID of the workflow instance that was triggered
workflow_name The name of the workflow
workflow_first_job_queued_at The timestamp (UTC) of when the workflow instance started to queue
workflow_first_job_started_at The timestamp (UTC) of when the workflow instance started to run
workflow_stopped_at The timestamp (UTC) of when the workflow instance stopped
is_workflow_successful Y/N flag of whether all jobs in the workflow were successfully ran
Job-level attributes job_name The name of the job (the name the customer sees in the UI)
job_id The ID of the job run instance that was triggered
job_run_number The number of the job run instance that was triggered
job_run_date The date (UTC) of the job run instance began
job_run_queued_at The timestamp (UTC) of when the job started to queue
job_run_started_at The timestamp (UTC) of when the job started to run
job_run_stopped_at The timestamp (UTC) of when the job stopped
job_build_status The status of the job run instance
resource_class The resource class of the job run instance
operating_system The operating system of the job run instance
executor The executor of the job run instance
parallelism The parallelism of the job run instance
job_run_seconds The duration in seconds of the job run instance
median_cpu_utilization_pct 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.
max_cpu_utilization_pct 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.
median_ram_utilization_pct 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.
max_ram_utilization_pct 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.
Credit consumption metrics compute_credits The compute credits consumed by this job run instance
dlc_credits The docker-layer caching credits consumed by this job run instance
user_credits The user credits consumed by this job run instance
storage_credits 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 by navigating to Plan > Plan Usage.
network_credits The network credits consumed by this job run instance
lease_credits The lease credits consumed by this job run instance
lease_overage_credits The lease overage credits consumed by this job run instance
ipranges_credits The IP ranges credits consumed by this job run instance
total_credits The total credits consumed by this job run instance

Create a usage export

Submits a request to create a usage export for an organization.

Authorizations:
api_key_headerbasic_auth
path Parameters
org_id
required
string
Example: b9291e0d-a11e-41fb-8517-c545388b5953

An opaque identifier of an organization.

Request Body schema: application/json
required
start
required
string <date-time>

The start date & time (inclusive) of the range from which data will be pulled. Must be no more than one year ago.

end
required
string <date-time>

The end date & time (inclusive) of the range from which data will be pulled. Must be no more than 31 days after start.

shared_org_ids
Array of strings <uuid> [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z",
  • "shared_org_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "usage_export_job_id": "7cd4bded-f639-433a-876b-1a8ea9f53127",
  • "state": "created",
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z",
  • "download_urls": []
}

Get a usage export

Gets a usage export for an organization.

Authorizations:
api_key_headerbasic_auth
path Parameters
org_id
required
string
Example: b9291e0d-a11e-41fb-8517-c545388b5953

An opaque identifier of an organization.

usage_export_job_id
required
string <uuid>
Example: e8235eed-f121-4ae3-9c72-2719d6572818

An opaque identifier of a usage export job.

Responses

Response samples

Content type
application/json
{
  • "usage_export_job_id": "7cd4bded-f639-433a-876b-1a8ea9f53127",
  • "state": "created",
  • "download_urls": [],
  • "error_reason": "string"
}