Download OpenAPI specification:
This document outlines the endpoints and resources that are a part of the CircleCI API v2.
Gets a list of project and expression restrictions associated with a context.
context_id required | string Example: be8bb2e3-c3d6-4098-89f4-572ff976ba9a An opaque identifier of a context. |
{- "items": [
- {
- "context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686",
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
- "name": "string",
- "restriction_type": "project",
- "restriction_value": "string"
}
], - "next_page_token": "string"
}
Creates project or expression restriction on a context.
context_id required | string Example: be8bb2e3-c3d6-4098-89f4-572ff976ba9a An opaque identifier of a context. |
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 |
{- "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
- "restriction_type": "project",
- "restriction_value": "405d8375-3514-403b-8c43-83ae74cfe0e9"
}
{- "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"
}
Deletes a project or expression restriction on a context.
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. |
{- "message": "Context restriction deleted."
}
Endpoints relating to pipelines. Get information about your pipelines. Trigger or continue a 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
).
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. |
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. |
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. |
{- "definition_id": "2338d0ae-5541-4bbf-88a2-55e9f7281f80",
- "config": {
- "branch": "main"
}, - "checkout": {
- "tag": "v2"
}, - "parameters": {
- "example_param": "my value",
- "example_param2": true,
- "example_param3": 3
}
}
{- "message": "Ignoring pipeline due to CI skip in the commit"
}
List all pipeline definitions for a given project. Share feedback about our Project Administration APIs.
project_id required | string Example: 39723015-b399-4601-9ff6-bd1bfbed8fa8 An opaque identifier of a project. |
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "some pipeline",
- "description": "some pipeline description",
- "created_at": "2019-08-24T14:15:22Z",
- "config_source": {
- "provider": "github_app",
- "repo": {
- "full_name": "some-org/some-repo-name",
- "external_id": "some-repo-id"
}, - "file_path": ".circleci/some-pipeline.yml"
}, - "checkout_source": {
- "provider": "github_app",
- "repo": {
- "full_name": "some-org/some-repo-name",
- "external_id": "some-repo-id"
}
}
}
]
}
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.
project_id required | string Example: 39723015-b399-4601-9ff6-bd1bfbed8fa8 An opaque identifier of a project. |
name required | string The name of the pipeline definition. |
description | string The description of the pipeline definition. |
required | object The resource that stores the CircleCI config YAML used for this pipeline definition. |
required | object The resource to be used when running the |
{- "name": "Some pipeline name",
- "description": "Some pipeline description",
- "config_source": {
- "provider": "github_app",
- "repo": {
- "external_id": "some-repo-id"
}, - "file_path": ".circleci/some-pipeline.yml"
}, - "checkout_source": {
- "provider": "github_app",
- "repo": {
- "external_id": "some-repo-id"
}
}
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "some pipeline",
- "description": "some pipeline description",
- "created_at": "2019-08-24T14:15:22Z",
- "config_source": {
- "provider": "github_app",
- "repo": {
- "full_name": "some-org/some-repo-name",
- "external_id": "some-repo-id"
}, - "file_path": ".circleci/some-pipeline.yml"
}, - "checkout_source": {
- "provider": "github_app",
- "repo": {
- "full_name": "some-org/some-repo-name",
- "external_id": "some-repo-id"
}
}
}
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.
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. |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "some pipeline",
- "description": "some pipeline description",
- "created_at": "2019-08-24T14:15:22Z",
- "config_source": {
- "provider": "github_app",
- "repo": {
- "full_name": "some-org/some-repo-name",
- "external_id": "some-repo-id"
}, - "file_path": ".circleci/some-pipeline.yml"
}, - "checkout_source": {
- "provider": "github_app",
- "repo": {
- "full_name": "some-org/some-repo-name",
- "external_id": "some-repo-id"
}
}
}
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.
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. |
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 |
{- "name": "Some pipeline name",
- "description": "Some pipeline description",
- "config_source": {
- "file_path": ".circleci/some-pipeline.yml"
}, - "checkout_source": {
- "provider": "github_app",
- "repo": {
- "external_id": "some-repo-id"
}
}
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "some pipeline",
- "description": "some pipeline description",
- "created_at": "2019-08-24T14:15:22Z",
- "config_source": {
- "provider": "github_app",
- "repo": {
- "full_name": "some-org/some-repo-name",
- "external_id": "some-repo-id"
}, - "file_path": ".circleci/some-pipeline.yml"
}, - "checkout_source": {
- "provider": "github_app",
- "repo": {
- "full_name": "some-org/some-repo-name",
- "external_id": "some-repo-id"
}
}
}
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.
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. |
{- "message": "string"
}
[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.
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. |
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. |
{- "advanced": {
- "autocancel_builds": true,
- "build_fork_prs": true,
- "build_prs_only": true,
- "disable_ssh": true,
- "forks_receive_secret_env_vars": true,
- "oss": true,
- "set_github_status": true,
- "setup_workflows": true,
- "write_settings_requires_admin": true,
- "pr_only_branch_overrides": [
- "string"
]
}
}
[EXPERIMENTAL] Returns a list of the advanced settings for a CircleCI project, whether enabled (true) or not (false).
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. |
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. |
{- "advanced": {
- "autocancel_builds": true,
- "build_fork_prs": true,
- "build_prs_only": true,
- "disable_ssh": true,
- "forks_receive_secret_env_vars": true,
- "oss": true,
- "set_github_status": true,
- "setup_workflows": true,
- "write_settings_requires_admin": true,
- "pr_only_branch_overrides": [
- "string"
]
}
}
[EXPERIMENTAL] Updates one or more of the advanced settings for a CircleCI project.
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. |
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. |
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 |
{- "advanced": {
- "autocancel_builds": false,
- "build_prs_only": true,
- "pr_only_branch_overrides": [
- "main"
]
}
}
{- "advanced": {
- "autocancel_builds": true,
- "build_fork_prs": true,
- "build_prs_only": true,
- "disable_ssh": true,
- "forks_receive_secret_env_vars": true,
- "oss": true,
- "set_github_status": true,
- "setup_workflows": true,
- "write_settings_requires_admin": true,
- "pr_only_branch_overrides": [
- "string"
]
}
}
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.
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. |
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "event_name": "some event name",
- "created_at": "2019-08-24T14:15:22Z",
- "event_source": {
- "provider": "github_app",
- "repo": {
- "full_name": "some-org/some-repo-name",
- "external_id": "some-repo-id"
}, - "webhook": {
- "sender": "datadog"
}
}, - "event_preset": "all-pushes",
- "checkout_ref": "some-checkout-ref",
- "config_ref": "some-config-ref"
}
]
}
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.
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. |
required | object The source of events to use for this trigger. The |
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 |
checkout_ref | string The ref to use when checking out code for pipeline runs created from this trigger. Always required when |
config_ref | string The ref to use when fetching config for pipeline runs created from this trigger. Always required when |
event_name | string The name of the triggering event. This should only be set for triggers where |
{- "event_source": {
- "provider": "github_app",
- "repo": {
- "external_id": "some-repo-id"
}, - "webhook": {
- "sender": "some-webhook-sender"
}
}, - "event_preset": "all-pushes",
- "checkout_ref": "some-checkout-ref",
- "config_ref": "some-config-ref",
- "event_name": "some-event-name"
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "event_name": "some event name",
- "created_at": "2019-08-24T14:15:22Z",
- "event_source": {
- "provider": "github_app",
- "repo": {
- "full_name": "some-org/some-repo-name",
- "external_id": "some-repo-id"
}, - "webhook": {
- "sender": "datadog"
}
}, - "event_preset": "all-pushes",
- "checkout_ref": "some-checkout-ref",
- "config_ref": "some-config-ref"
}
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.
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. |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "event_name": "some event name",
- "created_at": "2019-08-24T14:15:22Z",
- "event_source": {
- "provider": "github_app",
- "repo": {
- "full_name": "some-org/some-repo-name",
- "external_id": "some-repo-id"
}, - "webhook": {
- "sender": "datadog"
}
}, - "event_preset": "all-pushes",
- "checkout_ref": "some-checkout-ref",
- "config_ref": "some-config-ref"
}
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.
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. |
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 |
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 |
object |
{- "event_preset": "all-pushes",
- "checkout_ref": "some-checkout-ref",
- "config_ref": "some-config-ref",
- "event_name": "some event name",
- "event_source": {
- "webhook": {
- "sender": "some sender"
}
}
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "event_name": "some event name",
- "created_at": "2019-08-24T14:15:22Z",
- "event_source": {
- "provider": "github_app",
- "repo": {
- "full_name": "some-org/some-repo-name",
- "external_id": "some-repo-id"
}, - "webhook": {
- "sender": "datadog"
}
}, - "event_preset": "all-pushes",
- "checkout_ref": "some-checkout-ref",
- "config_ref": "some-config-ref"
}
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.
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. |
{- "message": "string"
}
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
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 |
Submits a request to create a usage export for an organization.
org_id required | string Example: b9291e0d-a11e-41fb-8517-c545388b5953 An opaque identifier of an organization. |
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 |
shared_org_ids | Array of strings <uuid> [ items <uuid > ] |
{- "start": "2019-08-24T14:15:22Z",
- "end": "2019-08-24T14:15:22Z",
- "shared_org_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
{- "usage_export_job_id": "7cd4bded-f639-433a-876b-1a8ea9f53127",
- "state": "created",
- "start": "2019-08-24T14:15:22Z",
- "end": "2019-08-24T14:15:22Z",
}
Gets a usage export for an organization.
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. |
{- "usage_export_job_id": "7cd4bded-f639-433a-876b-1a8ea9f53127",
- "state": "created",
- "error_reason": "string"
}