redocly logoAPI 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

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

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

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

Pipeline

Endpoints related to creating and managing pipelines.

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

🧪 List pipeline definitions

[EXPERIMENTAL] List all pipeline definitions for a given project.

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

[EXPERIMENTAL] Create pipeline definition for a given project.

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

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

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

[EXPERIMENTAL] Get details for a pipeline definition.

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

[EXPERIMENTAL] Update pipeline definition.

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

[EXPERIMENTAL] Delete pipeline definition.

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

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

Trigger

Endpoints related to creating and managing triggers.

🧪 List pipeline definition triggers

[EXPERIMENTAL] List all triggers for a given pipeline definition.

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

[EXPERIMENTAL] Create trigger for a given project.

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
required
string

The name of the trigger.

description
string

The description of the trigger.

required
object

The source of events to use for this trigger.

event_preset
string

The name of the event preset to use when filtering events for this trigger.

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.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "some name",
  • "description": "some description",
  • "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

[EXPERIMENTAL] Get trigger for a given project.

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",
  • "name": "some name",
  • "description": "some description",
  • "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

[EXPERIMENTAL] Update trigger for a given project.

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
name
string

The name of the trigger.

description
string

The description of the trigger.

event_preset
string

The name of the event preset to use when filtering events for this trigger.

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.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "some name",
  • "description": "some description",
  • "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

[EXPERIMENTAL] Delete trigger for a given project.

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