API docs by Redocly

CircleCI API (v2)

Download OpenAPI specification:Download

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

[EXPERIMENTAL] Gets a list of project 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

[EXPERIMENTAL] Creates project 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
restriction_value
string

Responses

Request samples

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

Response samples

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

🧪 Delete context restriction

[EXPERIMENTAL] Deletes a project 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."
}

Project

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

🧪 Create a project

[EXPERIMENTAL] 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
Example: gh

The provider segment of a project or org slug, the first of the three. This may be a VCS. For projects that use GitLab or GitHub App, use circleci.

organization
required
string
Example: CircleCI-Public

The organization segment of a project or org slug, the second of the three. For GitHub OAuth or Bitbucket projects, this is the organization name. For projects that use GitLab or GitHub App, use the organization ID (found in Organization Settings).

project
required
string
Example: api-preview-docs

The project segment of a project slug, the third of the three. For GitHub OAuth or Bitbucket projects, this is the repository name. For projects that use GitLab or GitHub App, use the project ID (found in Project Settings).

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
Example: gh

The provider segment of a project or org slug, the first of the three. This may be a VCS. For projects that use GitLab or GitHub App, use circleci.

organization
required
string
Example: CircleCI-Public

The organization segment of a project or org slug, the second of the three. For GitHub OAuth or Bitbucket projects, this is the organization name. For projects that use GitLab or GitHub App, use the organization ID (found in Organization Settings).

project
required
string
Example: api-preview-docs

The project segment of a project slug, the third of the three. For GitHub OAuth or Bitbucket projects, this is the repository name. For projects that use GitLab or GitHub App, use the project ID (found in Project Settings).

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
Example: gh

The provider segment of a project or org slug, the first of the three. This may be a VCS. For projects that use GitLab or GitHub App, use circleci.

organization
required
string
Example: CircleCI-Public

The organization segment of a project or org slug, the second of the three. For GitHub OAuth or Bitbucket projects, this is the organization name. For projects that use GitLab or GitHub App, use the organization ID (found in Organization Settings).

project
required
string
Example: api-preview-docs

The project segment of a project slug, the third of the three. For GitHub OAuth or Bitbucket projects, this is the repository name. For projects that use GitLab or GitHub App, use the project ID (found in Project Settings).

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": {
    }
}

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 minute 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
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"
}

Pipeline

[Recommended] Trigger a new pipeline

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

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

The provider segment of a project or org slug, the first of the three. This may be a VCS. For projects that use GitHub App, use circleci.

organization
required
string
Example: CircleCI-Public

The organization segment of a project or org slug, the second of the three. For GitHub OAuth or Bitbucket projects, this is the organization name. For projects that use GitLab or GitHub App, use the organization ID (found in Organization Settings).

project
required
string
Example: api-preview-docs

The project segment of a project slug, the third of the three. For GitHub OAuth or Bitbucket projects, this is the repository name. For projects that use GitLab or GitHub App, use the project ID (found in Project Settings).

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
{
  • "state": "created",
  • "created_at": "2019-08-24T14:15:22Z",
  • "number": 25,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}