CircleCI API (v2)

Download OpenAPI specification:Download

License: MIT

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

Authentication

api_key_header

Project API tokens are not supported for API v2. Use a personal API token.

Security Scheme Type API Key
Header parameter name: Circle-Token

basic_auth

HTTP basic authentication. The username should be set as the circle-token value, and the password should be left blank. Note that project tokens are currently not supported on API v2.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

api_key_query

DEPRECATED - we will remove this option in the future. Project API tokens are not supported for API v2. Use a personal API token.

Security Scheme Type API Key
Query parameter name: circle-token

Context

List contexts

List all contexts for an owner.

query Parameters
owner-id
string <uuid>

The unique ID of the owner of the context. Specify either this or owner-slug.

owner-slug
string

A string that represents an organization. Specify either this or owner-id. Cannot be used for accounts.

owner-type
string
Enum: "account" "organization"

The type of the owner. Defaults to "organization". Accounts are only used as context owners in server.

page-token
string

A token to retrieve the next page of results.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/context',
  qs: {
    'owner-id': 'c65b68ef-e73b-4bf2-be9a-7a322a9df150',
    'page-token': 'NEXT_PAGE_TOKEN'
  },
  headers: {'Circle-Token': 'CIRCLE_TOKEN'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Create a new context

Creates a new context.

Request Body schema: application/json
name
required
string

The user defined name of the context.

required
object or object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "owner":
    {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "created_at": "2015-09-21T17:29:21.042Z"
}

Delete a context

path Parameters
context-id
required
string <uuid>

ID of the context (UUID)

Responses

Request samples

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://circleci.com/api/v2/context/%7Bcontext-id%7D',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Get a context

Returns basic information about a context.

path Parameters
context-id
required
string <uuid>

ID of the context (UUID)

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/context/%7Bcontext-id%7D',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "created_at": "2015-09-21T17:29:21.042Z"
}

List environment variables

List information about environment variables in a context, not including their values.

path Parameters
context-id
required
string <uuid>

ID of the context (UUID)

query Parameters
page-token
string

A token to retrieve the next page of results.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/context/%7Bcontext-id%7D/environment-variable',
  qs: {'page-token': 'SOME_STRING_VALUE'},
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Add or update an environment variable

Create or update an environment variable within a context. Returns information about the environment variable, not including its value.

path Parameters
context-id
required
string <uuid>

ID of the context (UUID)

env-var-name
required
string
Example: POSTGRES_USER

The name of the environment variable

Request Body schema: application/json
value
required
string

The value of the environment variable

Responses

Request samples

Content type
application/json
{
  • "value": "some-secret-value"
}

Response samples

Content type
application/json
Example
{
  • "variable": "POSTGRES_USER",
  • "created_at": "2015-09-21T17:29:21.042Z",
  • "updated_at": "2015-09-21T17:29:21.042Z",
  • "context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686"
}

Remove an environment variable

Delete an environment variable from a context.

path Parameters
env-var-name
required
string
Example: POSTGRES_USER

The name of the environment variable

context-id
required
string <uuid>

ID of the context (UUID)

Responses

Request samples

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://circleci.com/api/v2/context/%7Bcontext-id%7D/environment-variable/POSTGRES_USER',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

🧪 Get context restrictions

[EXPERIMENTAL] Gets a list of project restrictions associated with a context.

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

An opaque identifier of a context.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/context/be8bb2e3-c3d6-4098-89f4-572ff976ba9a/restrictions',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

🧪 Create context restriction

[EXPERIMENTAL] Creates project restriction on a context.

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

An opaque identifier of a context.

Request Body schema: application/json
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.

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

Request samples

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://circleci.com/api/v2/context/be8bb2e3-c3d6-4098-89f4-572ff976ba9a/restrictions/1c23d2cb-07b1-4a28-8af3-e369732050ed',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Insights

Get summary metrics and trends for a project across it's workflows and branches

Get summary metrics and trends for a project at workflow and branch level. Workflow runs going back at most 90 days are included in the aggregation window. Trends are only supported upto last 30 days. Please note that Insights is not a financial reporting tool and should not be used for precise credit reporting. Credit reporting from Insights does not use the same source of truth as the billing information that is found in the Plan Overview page in the CircleCI UI, nor does the underlying data have the same data accuracy guarantees as the billing information in the CircleCI UI. This may lead to discrepancies between credits reported from Insights and the billing information in the Plan Overview page of the CircleCI UI. For precise credit reporting, always use the Plan Overview page in the CircleCI UI.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

query Parameters
reporting-window
string
Enum: "last-7-days" "last-90-days" "last-24-hours" "last-30-days" "last-60-days"
Example: reporting-window=last-90-days

The time window used to calculate summary metrics. If not provided, defaults to last-90-days

branches
object
Example: branches=A single branch: ?branches=main or for multiple branches: ?branches=main&branches=feature&branches=dev

The names of VCS branches to include in branch-level workflow metrics.

workflow-names
object
Example: workflow-names=A single workflow name: ?workflow-names=build-test-deploy or for multiple workflow names: ?workflow-names=build&workflow-names=test-and-deploy.

The names of workflows to include in workflow-level metrics.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/insights/pages/gh/CircleCI-Public/api-preview-docs/summary',
  qs: {
    'reporting-window': 'SOME_STRING_VALUE',
    branches: 'SOME_OBJECT_VALUE',
    'workflow-names': 'SOME_OBJECT_VALUE'
  },
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "org_id": null,
  • "project_id": null,
  • "project_data":
    {
    },
  • "project_workflow_data":
    [
    ],
  • "project_workflow_branch_data":
    [
    ],
  • "all_branches":
    [
    ],
  • "all_workflows":
    [
    ]
}

Job timeseries data

Get timeseries data for all jobs within a workflow. Hourly granularity data is only retained for 48 hours while daily granularity data is retained for 90 days.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

workflow-name
required
string
Example: build-and-test

The name of the workflow.

query Parameters
branch
string

The name of a vcs branch. If not passed we will scope the API call to the default branch.

granularity
string
Enum: "daily" "hourly"
Example: granularity=hourly

The granularity for which to query timeseries data.

start-date
string <date-time>
Example: start-date=2020-08-21T13:26:29Z

Include only executions that started at or after this date. This must be specified if an end-date is provided.

end-date
string <date-time>
Example: end-date=2020-09-04T13:26:29Z

Include only executions that started before this date. This date can be at most 90 days after the start-date.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/insights/time-series/gh/CircleCI-Public/api-preview-docs/workflows/build-and-test/jobs',
  qs: {
    branch: 'SOME_STRING_VALUE',
    granularity: 'SOME_STRING_VALUE',
    'start-date': 'SOME_STRING_VALUE',
    'end-date': 'SOME_STRING_VALUE'
  },
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Get summary metrics with trends for the entire org, and for each project.

Gets aggregated summary metrics with trends for the entire org. Also gets aggregated metrics and trends for each project belonging to the org.

path Parameters
org-slug
required
string
Example: gh/CircleCI-Public

Org slug in the form vcs-slug/org-name. The / characters may be URL-escaped.

query Parameters
reporting-window
string
Enum: "last-7-days" "last-90-days" "last-24-hours" "last-30-days" "last-60-days"
Example: reporting-window=last-90-days

The time window used to calculate summary metrics. If not provided, defaults to last-90-days

project-names
object
Example: project-names=For a single project: ?project-names=some-project or for multiple projects: ?project-names=some-project1&project-names=some-project2

List of project names.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/insights/gh/CircleCI-Public/summary',
  qs: {'reporting-window': 'SOME_STRING_VALUE', 'project-names': 'SOME_OBJECT_VALUE'},
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "org_data":
    {
    },
  • "org_project_data":
    [
    ],
  • "all_projects":
    [
    ]
}

Get all branches for a project

Get a list of all branches for a specified project. The list will only contain branches currently available within Insights. The maximum number of branches returned by this endpoint is 5,000.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

query Parameters
workflow-name
string
Example: workflow-name=build-and-test

The name of a workflow. If not passed we will scope the API call to the project.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/insights/gh/CircleCI-Public/api-preview-docs/branches',
  qs: {'workflow-name': 'SOME_STRING_VALUE'},
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "org_id": null,
  • "project_id": null,
  • "branches":
    [
    ]
}

Get flaky tests for a project

Get a list of flaky tests for a given project. Flaky tests are branch agnostic. A flaky test is a test that passed and failed in the same commit.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/insights/gh/CircleCI-Public/api-preview-docs/flaky-tests',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "flaky-tests":
    [
    ],
  • "total-flaky-tests": 5
}

Get summary metrics for a project's workflows

Get summary metrics for a project's workflows. Workflow runs going back at most 90 days are included in the aggregation window. Metrics are refreshed daily, and thus may not include executions from the last 24 hours. Please note that Insights is not a financial reporting tool and should not be used for precise credit reporting. Credit reporting from Insights does not use the same source of truth as the billing information that is found in the Plan Overview page in the CircleCI UI, nor does the underlying data have the same data accuracy guarantees as the billing information in the CircleCI UI. This may lead to discrepancies between credits reported from Insights and the billing information in the Plan Overview page of the CircleCI UI. For precise credit reporting, always use the Plan Overview page in the CircleCI UI.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

query Parameters
page-token
string

A token to retrieve the next page of results.

all-branches
boolean

Whether to retrieve data for all branches combined. Use either this parameter OR the branch name parameter.

branch
string

The name of a vcs branch. If not passed we will scope the API call to the default branch.

reporting-window
string
Enum: "last-7-days" "last-90-days" "last-24-hours" "last-30-days" "last-60-days"
Example: reporting-window=last-90-days

The time window used to calculate summary metrics. If not provided, defaults to last-90-days

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/insights/gh/CircleCI-Public/api-preview-docs/workflows',
  qs: {
    'page-token': 'SOME_STRING_VALUE',
    'all-branches': 'SOME_BOOLEAN_VALUE',
    branch: 'SOME_STRING_VALUE',
    'reporting-window': 'SOME_STRING_VALUE'
  },
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Get recent runs of a workflow

Get recent runs of a workflow. Runs going back at most 90 days are returned. Please note that Insights is not a financial reporting tool and should not be used for precise credit reporting. Credit reporting from Insights does not use the same source of truth as the billing information that is found in the Plan Overview page in the CircleCI UI, nor does the underlying data have the same data accuracy guarantees as the billing information in the CircleCI UI. This may lead to discrepancies between credits reported from Insights and the billing information in the Plan Overview page of the CircleCI UI. For precise credit reporting, always use the Plan Overview page in the CircleCI UI.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

workflow-name
required
string
Example: build-and-test

The name of the workflow.

query Parameters
all-branches
boolean

Whether to retrieve data for all branches combined. Use either this parameter OR the branch name parameter.

branch
string

The name of a vcs branch. If not passed we will scope the API call to the default branch.

page-token
string

A token to retrieve the next page of results.

start-date
string <date-time>
Example: start-date=2020-08-21T13:26:29Z

Include only executions that started at or after this date. This must be specified if an end-date is provided.

end-date
string <date-time>
Example: end-date=2020-09-04T13:26:29Z

Include only executions that started before this date. This date can be at most 90 days after the start-date.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/insights/gh/CircleCI-Public/api-preview-docs/workflows/build-and-test',
  qs: {
    'all-branches': 'SOME_BOOLEAN_VALUE',
    branch: 'SOME_STRING_VALUE',
    'page-token': 'SOME_STRING_VALUE',
    'start-date': 'SOME_STRING_VALUE',
    'end-date': 'SOME_STRING_VALUE'
  },
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Get summary metrics for a project workflow's jobs.

Get summary metrics for a project workflow's jobs. Job runs going back at most 90 days are included in the aggregation window. Metrics are refreshed daily, and thus may not include executions from the last 24 hours. Please note that Insights is not a financial reporting tool and should not be used for precise credit reporting. Credit reporting from Insights does not use the same source of truth as the billing information that is found in the Plan Overview page in the CircleCI UI, nor does the underlying data have the same data accuracy guarantees as the billing information in the CircleCI UI. This may lead to discrepancies between credits reported from Insights and the billing information in the Plan Overview page of the CircleCI UI. For precise credit reporting, always use the Plan Overview page in the CircleCI UI.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

workflow-name
required
string
Example: build-and-test

The name of the workflow.

query Parameters
page-token
string

A token to retrieve the next page of results.

all-branches
boolean

Whether to retrieve data for all branches combined. Use either this parameter OR the branch name parameter.

branch
string

The name of a vcs branch. If not passed we will scope the API call to the default branch.

reporting-window
string
Enum: "last-7-days" "last-90-days" "last-24-hours" "last-30-days" "last-60-days"
Example: reporting-window=last-90-days

The time window used to calculate summary metrics. If not provided, defaults to last-90-days

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/insights/gh/CircleCI-Public/api-preview-docs/workflows/build-and-test/jobs',
  qs: {
    'page-token': 'SOME_STRING_VALUE',
    'all-branches': 'SOME_BOOLEAN_VALUE',
    branch: 'SOME_STRING_VALUE',
    'reporting-window': 'SOME_STRING_VALUE'
  },
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Get metrics and trends for workflows

Get the metrics and trends for a particular workflow on a single branch or all branches

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

workflow-name
required
string
Example: build-and-test

The name of the workflow.

query Parameters
all-branches
boolean

Whether to retrieve data for all branches combined. Use either this parameter OR the branch name parameter.

branch
string

The name of a vcs branch. If not passed we will scope the API call to the default branch.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/insights/gh/CircleCI-Public/api-preview-docs/workflows/build-and-test/summary',
  qs: {'all-branches': 'SOME_BOOLEAN_VALUE', branch: 'SOME_STRING_VALUE'},
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "metrics":
    {
    },
  • "trends":
    {
    },
  • "workflow_names":
    [
    ]
}

Get test metrics for a project's workflows

Get test metrics for a project's workflows. Currently tests metrics are calculated based on 10 most recent workflow runs.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

workflow-name
required
string
Example: build-and-test

The name of the workflow.

query Parameters
branch
string

The name of a vcs branch. If not passed we will scope the API call to the default branch.

all-branches
boolean

Whether to retrieve data for all branches combined. Use either this parameter OR the branch name parameter.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/insights/gh/CircleCI-Public/api-preview-docs/workflows/build-and-test/test-metrics',
  qs: {branch: 'SOME_STRING_VALUE', 'all-branches': 'SOME_BOOLEAN_VALUE'},
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "average_test_count": 0,
  • "most_failed_tests":
    [
    ],
  • "most_failed_tests_extra": 0,
  • "slowest_tests":
    [
    ],
  • "slowest_tests_extra": 0,
  • "total_test_runs": 0,
  • "test_runs":
    [
    ]
}

User

User Information

Provides information about the user that is currently signed in.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/me',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "login": "string",
  • "name": "string"
}

Collaborations

Provides the set of organizations of which a user is a member or a collaborator.

The set of organizations that a user can collaborate on is composed of:

  • Organizations that the current user belongs to across VCS types (e.g. BitBucket, GitHub)
  • The parent organization of repository that the user can collaborate on, but is not necessarily a member of
  • The organization of the current user's account

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/me/collaborations',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
[
  • {
    }
]

User Information

Provides information about the user with the given ID.

path Parameters
id
required
string <uuid>

The unique ID of the user.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/user/%7Bid%7D',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "login": "string",
  • "name": "string"
}

Pipeline

Get a list of pipelines

Returns all pipelines for the most recently built projects (max 250) you follow in an organization.

query Parameters
org-slug
string
Example: org-slug=gh/CircleCI-Public

Org slug in the form vcs-slug/org-name. For projects that use GitLab or GitHub App, use circleci as the vcs-slug and replace the org-name with the organization ID (found in Organization Settings).

page-token
string

A token to retrieve the next page of results.

mine
boolean

Only include entries created by your user.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/pipeline',
  qs: {
    'org-slug': 'SOME_STRING_VALUE',
    'page-token': 'SOME_STRING_VALUE',
    mine: 'SOME_BOOLEAN_VALUE'
  },
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Continue a pipeline

Continue a pipeline from the setup phase. For information on using pipeline parameters with dynamic configuration, see the Pipeline values and parameters docs.

Request Body schema: application/json
continuation-key
required
string (PipelineContinuationKey)

A pipeline continuation key.

configuration
required
string

A configuration string for the pipeline.

object

An object containing pipeline parameters and their values.

Responses

Request samples

Content type
application/json
{
  • "continuation-key": "string",
  • "configuration": "string",
  • "parameters":
    {
    }
}

Response samples

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

Get a pipeline by ID

Returns a pipeline by the pipeline ID.

path Parameters
pipeline-id
required
string <uuid>
Example: 5034460f-c7c4-4c43-9457-de07e2029e7b

The unique ID of the pipeline.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/pipeline/5034460f-c7c4-4c43-9457-de07e2029e7b',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "id": "5034460f-c7c4-4c43-9457-de07e2029e7b",
  • "errors":
    [
    ],
  • "project_slug": "gh/CircleCI-Public/api-preview-docs",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "number": "25",
  • "trigger_parameters":
    {
    },
  • "state": "created",
  • "created_at": "2019-08-24T14:15:22Z",
  • "trigger":
    {
    },
  • "vcs":
    {}
}

Get a pipeline's configuration

Returns a pipeline's configuration by ID.

path Parameters
pipeline-id
required
string <uuid>
Example: 5034460f-c7c4-4c43-9457-de07e2029e7b

The unique ID of the pipeline.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/pipeline/5034460f-c7c4-4c43-9457-de07e2029e7b/config',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "source": "string",
  • "compiled": "string",
  • "setup-config": "string",
  • "compiled-setup-config": "string"
}

Get a pipeline's workflows

Returns a paginated list of workflows by pipeline ID.

path Parameters
pipeline-id
required
string <uuid>
Example: 5034460f-c7c4-4c43-9457-de07e2029e7b

The unique ID of the pipeline.

query Parameters
page-token
string

A token to retrieve the next page of results.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/pipeline/5034460f-c7c4-4c43-9457-de07e2029e7b/workflow',
  qs: {'page-token': 'SOME_STRING_VALUE'},
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Get all pipelines

Returns all pipelines for this project.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

query Parameters
branch
string

The name of a vcs branch.

page-token
string

A token to retrieve the next page of results.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/pipeline',
  qs: {branch: 'SOME_STRING_VALUE', 'page-token': 'SOME_STRING_VALUE'},
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Trigger a new pipeline

Not yet available to projects that use GitLab or GitHub App. Triggers a new pipeline on the project.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

Request Body schema: application/json
branch
string

The branch where the pipeline ran. The HEAD commit on this branch was used for the pipeline. Note that branch and tag are mutually exclusive. To trigger a pipeline for a PR by number use pull/<number>/head for the PR ref or pull/<number>/merge for the merge ref (GitHub only).

tag
string

The tag used by the pipeline. The commit that this tag points to was used for the pipeline. Note that branch and tag are mutually exclusive.

object

An object containing pipeline parameters and their values.

Responses

Request samples

Content type
application/json
{
  • "branch": "feature/design-new-api",
  • "tag": "v3.1.4159",
  • "parameters":
    {
    }
}

Response samples

Content type
application/json
{
  • "id": "5034460f-c7c4-4c43-9457-de07e2029e7b",
  • "state": "created",
  • "number": "25",
  • "created_at": "2019-08-24T14:15:22Z"
}

Get your pipelines

Returns a sequence of all pipelines for this project triggered by the user.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

query Parameters
page-token
string

A token to retrieve the next page of results.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/pipeline/mine',
  qs: {'page-token': 'SOME_STRING_VALUE'},
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Get a pipeline by pipeline number

Returns a pipeline by the pipeline number.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

pipeline-number
required
any
Example: 123

The number of the pipeline.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/pipeline/123',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "id": "5034460f-c7c4-4c43-9457-de07e2029e7b",
  • "errors":
    [
    ],
  • "project_slug": "gh/CircleCI-Public/api-preview-docs",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "number": "25",
  • "trigger_parameters":
    {
    },
  • "state": "created",
  • "created_at": "2019-08-24T14:15:22Z",
  • "trigger":
    {
    },
  • "vcs":
    {}
}

Job

Get job details

Returns job details.

path Parameters
job-number
required
any
Example: 123

The number of the job.

project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/job/123',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "web_url": "string",
  • "project":
    {},
  • "parallel_runs":
    [
    ],
  • "started_at": "2019-08-24T14:15:22Z",
  • "latest_workflow":
    {
    },
  • "name": "string",
  • "executor":
    {
    },
  • "parallelism": 0,
  • "status": "success",
  • "number": 0,
  • "pipeline":
    {
    },
  • "duration": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "messages":
    [
    ],
  • "contexts":
    [
    ],
  • "organization":
    {
    },
  • "queued_at": "2019-08-24T14:15:22Z",
  • "stopped_at": "2019-08-24T14:15:22Z"
}

Cancel job

Cancel job with a given job number.

path Parameters
job-number
required
any
Example: 123

The number of the job.

project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

Responses

Request samples

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/job/123/cancel',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Get a job's artifacts

Returns a job's artifacts.

path Parameters
job-number
required
any
Example: 123

The number of the job.

project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/123/artifacts',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Get test metadata

Get test metadata for a build. In the rare case where there is more than 250MB of test data on the job, no results will be returned.

path Parameters
job-number
required
any
Example: 123

The number of the job.

project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/123/tests',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Workflow

Get a workflow

Returns summary fields of a workflow by ID.

path Parameters
id
required
string <uuid>
Example: 5034460f-c7c4-4c43-9457-de07e2029e7b

The unique ID of the workflow.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/workflow/5034460f-c7c4-4c43-9457-de07e2029e7b',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "pipeline_id": "5034460f-c7c4-4c43-9457-de07e2029e7b",
  • "canceled_by": "026a6d28-c22e-4aab-a8b4-bd7131a8ea35",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "build-and-test",
  • "project_slug": "gh/CircleCI-Public/api-preview-docs",
  • "errored_by": "c6e40f70-a80a-4ccc-af88-8d985a7bc622",
  • "tag": "setup",
  • "status": "success",
  • "started_by": "03987f6a-4c27-4dc1-b6ab-c7e83bb3e713",
  • "pipeline_number": "25",
  • "created_at": "2019-08-24T14:15:22Z",
  • "stopped_at": "2019-08-24T14:15:22Z"
}

Approve a job

Approves a pending approval job in a workflow.

path Parameters
approval_request_id
required
string <uuid>

The ID of the job being approved.

id
required
string <uuid>
Example: 5034460f-c7c4-4c43-9457-de07e2029e7b

The unique ID of the workflow.

Responses

Request samples

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://circleci.com/api/v2/workflow/5034460f-c7c4-4c43-9457-de07e2029e7b/approve/%7Bapproval_request_id%7D',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Cancel a workflow

Cancels a running workflow.

path Parameters
id
required
string <uuid>
Example: 5034460f-c7c4-4c43-9457-de07e2029e7b

The unique ID of the workflow.

Responses

Request samples

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://circleci.com/api/v2/workflow/5034460f-c7c4-4c43-9457-de07e2029e7b/cancel',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Get a workflow's jobs

Returns a sequence of jobs for a workflow.

path Parameters
id
required
string <uuid>
Example: 5034460f-c7c4-4c43-9457-de07e2029e7b

The unique ID of the workflow.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/workflow/5034460f-c7c4-4c43-9457-de07e2029e7b/job',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Rerun a workflow

Reruns a workflow.

path Parameters
id
required
string <uuid>
Example: 5034460f-c7c4-4c43-9457-de07e2029e7b

The unique ID of the workflow.

Request Body schema: application/json
enable_ssh
boolean

Whether to enable SSH access for the triggering user on the newly-rerun job. Requires the jobs parameter to be used and so is mutually exclusive with the from_failed parameter.

from_failed
boolean

Whether to rerun the workflow from the failed job. Mutually exclusive with the jobs parameter.

jobs
Array of strings <uuid>

A list of job IDs to rerun.

sparse_tree
boolean

Completes rerun using sparse trees logic, an optimization for workflows that have disconnected subgraphs. Requires jobs parameter and so is mutually exclusive with the from_failed parameter.

Responses

Request samples

Content type
application/json
{
  • "enable_ssh": false,
  • "from_failed": false,
  • "jobs":
    [
    ],
  • "sparse_tree": false
}

Response samples

Content type
application/json
{
  • "workflow_id": "0e53027b-521a-4c40-9042-47e72b3c63a3"
}

Webhook

List webhooks

Get a list of outbound webhooks that match the given scope-type and scope-id

query Parameters
scope-id
required
string <uuid>

ID of the scope being used (at the moment, only project ID is supported)

scope-type
required
string
Value: "project"

Type of the scope being used

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/webhook',
  qs: {'scope-id': 'SOME_STRING_VALUE', 'scope-type': 'SOME_STRING_VALUE'},
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Create an outbound webhook

Creates an outbound webhook.

Request Body schema: application/json
name
required
string

Name of the webhook

events
required
Array of strings
Items Enum: "workflow-completed" "job-completed"

Events that will trigger the webhook

url
required
string

URL to deliver the webhook to. Note: protocol must be included as well (only https is supported)

verify-tls
required
boolean

Whether to enforce TLS certificate verification when delivering the webhook

signing-secret
required
string

Secret used to build an HMAC hash of the payload and passed as a header in the webhook request

required
object

The scope in which the relevant events that will trigger webhooks

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "events":
    [
    ],
  • "url": "string",
  • "verify-tls": true,
  • "signing-secret": "string",
  • "scope":
    {
    }
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "verify-tls": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "signing-secret": "string",
  • "updated-at": "2015-09-21T17:29:21.042Z",
  • "name": "string",
  • "created-at": "2015-09-21T17:29:21.042Z",
  • "scope":
    {
    },
  • "events":
    [
    ]
}

Delete an outbound webhook

Deletes an outbound webhook

path Parameters
webhook-id
required
string <uuid>

ID of the webhook (UUID)

Responses

Request samples

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://circleci.com/api/v2/webhook/%7Bwebhook-id%7D',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Update an outbound webhook

Updates an outbound webhook.

path Parameters
webhook-id
required
string <uuid>

ID of the webhook (UUID)

Request Body schema: application/json
name
string

Name of the webhook

events
Array of strings
Items Enum: "workflow-completed" "job-completed"

Events that will trigger the webhook

url
string

URL to deliver the webhook to. Note: protocol must be included as well (only https is supported)

signing-secret
string

Secret used to build an HMAC hash of the payload and passed as a header in the webhook request

verify-tls
boolean

Whether to enforce TLS certificate verification when delivering the webhook

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "events":
    [
    ],
  • "url": "string",
  • "signing-secret": "string",
  • "verify-tls": true
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "verify-tls": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "signing-secret": "string",
  • "updated-at": "2015-09-21T17:29:21.042Z",
  • "name": "string",
  • "created-at": "2015-09-21T17:29:21.042Z",
  • "scope":
    {
    },
  • "events":
    [
    ]
}

Get a webhook

Get an outbound webhook by id.

path Parameters
webhook-id
required
string <uuid>

ID of the webhook (UUID)

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/webhook/%7Bwebhook-id%7D',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "url": "string",
  • "verify-tls": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "signing-secret": "string",
  • "updated-at": "2015-09-21T17:29:21.042Z",
  • "name": "string",
  • "created-at": "2015-09-21T17:29:21.042Z",
  • "scope":
    {
    },
  • "events":
    [
    ]
}

OIDC Token Management

Endpoints related to manage oidc identity tokens

Delete org-level claims

Deletes org-level custom claims of OIDC identity tokens

path Parameters
orgID
required
string <uuid>
query Parameters
claims
required
string

comma separated list of claims to delete. Valid values are "audience" and "ttl".

Responses

Request samples

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://circleci.com/api/v2/org/%7BorgID%7D/oidc-custom-claims',
  qs: {claims: 'SOME_STRING_VALUE'},
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "audience":
    [
    ],
  • "audience_updated_at": "2019-08-24T14:15:22Z",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  • "ttl": "string",
  • "ttl_updated_at": "2019-08-24T14:15:22Z"
}

Get org-level claims

Fetches org-level custom claims of OIDC identity tokens

path Parameters
orgID
required
string <uuid>

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/org/%7BorgID%7D/oidc-custom-claims',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "audience":
    [
    ],
  • "audience_updated_at": "2019-08-24T14:15:22Z",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  • "ttl": "string",
  • "ttl_updated_at": "2019-08-24T14:15:22Z"
}

Patch org-level claims

Creates/Updates org-level custom claims of OIDC identity tokens

path Parameters
orgID
required
string <uuid>
Request Body schema: application/json
audience
Array of strings
ttl
string (JSONDuration) ^([0-9]+(ms|s|m|h|d|w)){1,7}$

Responses

Request samples

Content type
application/json
{
  • "audience":
    [
    ],
  • "ttl": "string"
}

Response samples

Content type
application/json
{
  • "audience":
    [
    ],
  • "audience_updated_at": "2019-08-24T14:15:22Z",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  • "ttl": "string",
  • "ttl_updated_at": "2019-08-24T14:15:22Z"
}

Delete project-level claims

Deletes project-level custom claims of OIDC identity tokens

path Parameters
orgID
required
string <uuid>
projectID
required
string <uuid>
query Parameters
claims
required
string

comma separated list of claims to delete. Valid values are "audience" and "ttl".

Responses

Request samples

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://circleci.com/api/v2/org/%7BorgID%7D/project/%7BprojectID%7D/oidc-custom-claims',
  qs: {claims: 'SOME_STRING_VALUE'},
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "audience":
    [
    ],
  • "audience_updated_at": "2019-08-24T14:15:22Z",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  • "ttl": "string",
  • "ttl_updated_at": "2019-08-24T14:15:22Z"
}

Get project-level claims

Fetches project-level custom claims of OIDC identity tokens

path Parameters
orgID
required
string <uuid>
projectID
required
string <uuid>

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/org/%7BorgID%7D/project/%7BprojectID%7D/oidc-custom-claims',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "audience":
    [
    ],
  • "audience_updated_at": "2019-08-24T14:15:22Z",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  • "ttl": "string",
  • "ttl_updated_at": "2019-08-24T14:15:22Z"
}

Patch project-level claims

Creates/Updates project-level custom claims of OIDC identity tokens

path Parameters
orgID
required
string <uuid>
projectID
required
string <uuid>
Request Body schema: application/json
audience
Array of strings
ttl
string (JSONDuration) ^([0-9]+(ms|s|m|h|d|w)){1,7}$

Responses

Request samples

Content type
application/json
{
  • "audience":
    [
    ],
  • "ttl": "string"
}

Response samples

Content type
application/json
{
  • "audience":
    [
    ],
  • "audience_updated_at": "2019-08-24T14:15:22Z",
  • "org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
  • "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  • "ttl": "string",
  • "ttl_updated_at": "2019-08-24T14:15:22Z"
}

Policy Management

Endpoints related to managing policies and making policy decisions

Retrieves the owner's decision audit logs.

This endpoint will return a list of decision audit logs that were made using this owner's policies.

path Parameters
ownerID
required
string
context
required
string
query Parameters
status
string

Return decisions matching this decision status.

after
string <date-time>

Return decisions made after this date.

before
string <date-time>

Return decisions made before this date.

branch
string

Return decisions made on this branch.

project_id
string

Return decisions made for this project.

build_number
string

Return decisions made for this build number.

offset
integer

Sets the offset when retrieving the decisions, for paging.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/owner/%7BownerID%7D/context/%7Bcontext%7D/decision',
  qs: {
    status: 'SOME_STRING_VALUE',
    after: 'SOME_STRING_VALUE',
    before: 'SOME_STRING_VALUE',
    branch: 'SOME_STRING_VALUE',
    project_id: 'SOME_STRING_VALUE',
    build_number: 'SOME_STRING_VALUE',
    offset: 'SOME_INTEGER_VALUE'
  },
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
[
  • {
    }
]

Makes a decision

This endpoint will evaluate input data (config+metadata) against owner's stored policies and return a decision.

path Parameters
ownerID
required
string
context
required
string
Request Body schema: application/json
input
required
string
metadata
object

Responses

Request samples

Content type
application/json
{
  • "input": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "enabled_rules":
    [
    ],
  • "hard_failures":
    [
    ],
  • "reason": "string",
  • "soft_failures":
    [
    ],
  • "status": "string"
}

Get the decision settings

This endpoint retrieves the current decision settings (eg enable/disable policy evaluation)

path Parameters
ownerID
required
string
context
required
string

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/owner/%7BownerID%7D/context/%7Bcontext%7D/decision/settings',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "enabled": true
}

Set the decision settings

This endpoint allows modifying decision settings (eg enable/disable policy evaluation)

path Parameters
ownerID
required
string
context
required
string
Request Body schema: application/json
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "enabled": true
}

Retrieves the owner's decision audit log by given decisionID

This endpoint will retrieve a decision for a given decision log ID

path Parameters
ownerID
required
string
context
required
string
decisionID
required
string

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/owner/%7BownerID%7D/context/%7Bcontext%7D/decision/%7BdecisionID%7D',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "created_at": "2019-08-24T14:15:22Z",
  • "decision":
    {
    },
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "metadata":
    {
    },
  • "policies":
    {
    },
  • "time_taken_ms": 0
}

Retrieves Policy Bundle for a given decision log ID

This endpoint will retrieve a policy bundle for a given decision log ID

path Parameters
ownerID
required
string
context
required
string
decisionID
required
string

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/owner/%7BownerID%7D/context/%7Bcontext%7D/decision/%7BdecisionID%7D/policy-bundle',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "property1":
    [
    ],
  • "property2":
    [
    ]
}

Retrieves Policy Bundle

This endpoint will retrieve a policy bundle

path Parameters
ownerID
required
string
context
required
string

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/owner/%7BownerID%7D/context/%7Bcontext%7D/policy-bundle',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "property1":
    [
    ],
  • "property2":
    [
    ]
}

Creates policy bundle for the context

This endpoint replaces the current policy bundle with the provided policy bundle

path Parameters
ownerID
required
string
context
required
string
query Parameters
dry
boolean
Request Body schema: application/json
object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "created":
    [
    ],
  • "deleted":
    [
    ],
  • "modified":
    [
    ]
}

Retrieves a policy document

This endpoint will retrieve a policy document.

path Parameters
ownerID
required
string
context
required
string
policyName
required
string

the policy name set by the rego policy_name rule

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/owner/%7BownerID%7D/context/%7Bcontext%7D/policy-bundle/%7BpolicyName%7D',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "content": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": "string",
  • "name": "string"
}

Project

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

Get a project

Retrieves a project by project slug.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "slug": "gh/CircleCI-Public/api-preview-docs",
  • "name": "api-preview-docs",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "organization_name": "CircleCI-Public",
  • "organization_slug": "CircleCI-Public",
  • "organization_id": "CircleCI-Public",
  • "vcs_info":
    {}
}

Create a new checkout key

Not available to projects that use GitLab or GitHub App. Creates a new checkout key. This API request is only usable with a user API token. Please ensure that you have authorized your account with GitHub before creating user keys. This is necessary to give CircleCI the permission to create a user key associated with your GitHub user account. You can find this page by visiting Project Settings > Checkout SSH Keys

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

Request Body schema: application/json
type
required
string (CheckoutKeyInputType)
Enum: "user-key" "deploy-key"

The type of checkout key to create. This may be either deploy-key or user-key.

Responses

Request samples

Content type
application/json
{
  • "type": "deploy-key"
}

Response samples

Content type
application/json
{
  • "public-key": "ssh-rsa ...",
  • "type": "deploy-key",
  • "fingerprint": "c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f",
  • "preferred": true,
  • "created-at": "2015-09-21T17:29:21.042Z"
}

Get all checkout keys

Returns a sequence of checkout keys for :project.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

query Parameters
digest
string
Enum: "sha256" "md5"

The fingerprint digest type to return. This may be either md5 or sha256. If not passed, defaults to md5.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/checkout-key',
  qs: {digest: 'SOME_STRING_VALUE'},
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Delete a checkout key

Deletes the checkout key via md5 or sha256 fingerprint. sha256 keys should be url-encoded.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

fingerprint
required
string
Example: c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f

An SSH key fingerprint.

Responses

Request samples

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/checkout-key/c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Get a checkout key

Returns an individual checkout key via md5 or sha256 fingerprint. sha256 keys should be url-encoded.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

fingerprint
required
string
Example: c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f

An SSH key fingerprint.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/checkout-key/c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "public-key": "ssh-rsa ...",
  • "type": "deploy-key",
  • "fingerprint": "c9:0b:1c:4f:d5:65:56:b9:ad:88:f9:81:2b:37:74:2f",
  • "preferred": true,
  • "created-at": "2015-09-21T17:29:21.042Z"
}

Create an environment variable

Creates a new environment variable.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

Request Body schema: application/json
name
required
string

The name of the environment variable.

value
required
string

The value of the environment variable.

Responses

Request samples

Content type
application/json
{
  • "name": "foo",
  • "value": "xxxx1234"
}

Response samples

Content type
application/json
{
  • "name": "foo",
  • "value": "xxxx1234",
  • "created-at": "#joda/inst 2023-04-14T21:20:14+0000"
}

List all environment variables

Returns four 'x' characters, in addition to the last four ASCII characters of the value, consistent with the display of environment variable values on the CircleCI website.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/envvar',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Delete an environment variable

Deletes the environment variable named :name.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

name
required
string
Example: foo

The name of the environment variable.

Responses

Request samples

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/envvar/foo',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Get a masked environment variable

Returns the masked value of environment variable :name.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

name
required
string
Example: foo

The name of the environment variable.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/envvar/foo',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "name": "foo",
  • "value": "xxxx1234",
  • "created-at": "#joda/inst 2023-04-14T21:20:14+0000"
}

🧪 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.

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

Request samples

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

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).

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

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/settings',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

🧪 Update project settings

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

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

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

Schedule

Get all schedules

Returns all schedules for this project.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

query Parameters
page-token
string

A token to retrieve the next page of results.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/project/gh/CircleCI-Public/api-preview-docs/schedule',
  qs: {'page-token': 'SOME_STRING_VALUE'},
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

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

Create a schedule

Not yet available to projects that use GitLab or GitHub App. Creates a schedule and returns the created schedule.

path Parameters
project-slug
required
string
Example: gh/CircleCI-Public/api-preview-docs

Project slug in the form vcs-slug/org-name/repo-name. The / characters may be URL-escaped. For projects that use GitLab or GitHub App, use circleci as the vcs-slug, replace org-name with the organization ID (found in Organization Settings), and replace repo-name with the project ID (found in Project Settings).

Request Body schema: application/json
name
required
string

Name of the schedule.

required
object or object

Timetable that specifies when a schedule triggers.

attribution-actor
required
string
Enum: "current" "system"

The attribution-actor of the scheduled pipeline.

required
object

Pipeline parameters represented as key-value pairs. Must contain branch or tag.

description
string

Description of the schedule.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "timetable":
    {
    },
  • "attribution-actor": "current",
  • "parameters":
    {
    },
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "timetable":
    {
    },
  • "updated-at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "created-at": "2019-08-24T14:15:22Z",
  • "project-slug": "gh/CircleCI-Public/api-preview-docs",
  • "parameters":
    {
    },
  • "actor":
    {
    },
  • "description": "string"
}

Update a schedule

Not yet available to projects that use GitLab or GitHub App. Updates a schedule and returns the updated schedule.

path Parameters
schedule-id
required
string <uuid>

The unique ID of the schedule.

Request Body schema: application/json
description
string

Description of the schedule.

name
string

Name of the schedule.

object

Timetable that specifies when a schedule triggers.

attribution-actor
string
Enum: "current" "system"

The attribution-actor of the scheduled pipeline.

object

Pipeline parameters represented as key-value pairs. Must contain branch or tag.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "timetable":
    {
    },
  • "attribution-actor": "current",
  • "parameters":
    {
    }
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "timetable":
    {
    },
  • "updated-at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "created-at": "2019-08-24T14:15:22Z",
  • "project-slug": "gh/CircleCI-Public/api-preview-docs",
  • "parameters":
    {
    },
  • "actor":
    {
    },
  • "description": "string"
}

Get a schedule

Get a schedule by id.

path Parameters
schedule-id
required
string <uuid>

The unique ID of the schedule.

Responses

Request samples

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://circleci.com/api/v2/schedule/%7Bschedule-id%7D',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "timetable":
    {
    },
  • "updated-at": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "created-at": "2019-08-24T14:15:22Z",
  • "project-slug": "gh/CircleCI-Public/api-preview-docs",
  • "parameters":
    {
    },
  • "actor":
    {
    },
  • "description": "string"
}

Delete a schedule

Not yet available to projects that use GitLab or GitHub App. Deletes the schedule by id.

path Parameters
schedule-id
required
string <uuid>

The unique ID of the schedule.

Responses

Request samples

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://circleci.com/api/v2/schedule/%7Bschedule-id%7D',
  headers: {authorization: 'Basic REPLACE_BASIC_AUTH'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Response samples

Content type
application/json
{
  • "message": "string"
}
Scroll down for code samples, example requests and responses. Above each snippet you can change the language / framework used to make the request.