Documentation Powered by ReDoc

CircleCI API (v2)

Download OpenAPI specification:Download

License: MIT

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

Authentication

api_key_header

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

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

Context

Create a new context

Authorizations:
api_key_headerbasic_authapi_key_query
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"
}

List contexts

List all contexts for an owner.

Authorizations:
api_key_headerbasic_authapi_key_query
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: {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 context

Returns basic information about a context.

Authorizations:
api_key_headerbasic_authapi_key_query
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"
}

Delete a context

Authorizations:
api_key_headerbasic_authapi_key_query
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"
}

List environment variables

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

Authorizations:
api_key_headerbasic_authapi_key_query
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/environment-variable',
  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"
}

Remove an environment variable

Delete an environment variable from a context.

Authorizations:
api_key_headerbasic_authapi_key_query
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"
}

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.

Authorizations:
api_key_headerbasic_authapi_key_query
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
Select ...
MessageResponse
{
  • "variable": "POSTGRES_USER",
  • "created_at": "2015-09-21T17:29:21.042Z",
  • "context_id": "f31d7249-b7b1-4729-b3a4-ec0ba07b4686"
}

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. Metrics are refreshed daily, and thus may not include executions from the last 24 hours. Please note that Insights is not a real time financial reporting tool and should not be used for credit reporting. The most up to date credit information can be found in Plan Overview in the CircleCI UI.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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.

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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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.

timeseries-granularity
string
Enum: "daily" "hourly"
Example: timeseries-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',
    'timeseries-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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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
null

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 faliled in the same commit.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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

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 real time financial reporting tool and should not be used for credit reporting. The most up to date credit information can be found in Plan Overview in the CircleCI UI.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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.

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 real time financial reporting tool and should not be used for credit reporting. The most up to date credit information can be found in Plan Overview in the CircleCI UI.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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 real time financial reporting tool and should not be used for credit reporting. The most up to date credit information can be found in Plan Overview in the CircleCI UI.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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.

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

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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.

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.

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', branches: '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
{
  • "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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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 (Preview)

User Information

Provides information about the user that is currently signed in.

Authorizations:
api_key_headerbasic_authapi_key_query

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
Authorizations:
api_key_headerbasic_authapi_key_query

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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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

Org slug in the form vcs-slug/org-name

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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

Authorizations:
api_key_headerbasic_authapi_key_query
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"
}

Trigger a new pipeline

Triggers a new pipeline on the project.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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 all pipelines

Returns all pipelines for this project.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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

Get your pipelines

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

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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 (Preview)

Get job details

Returns job details.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

Authorizations:
api_key_headerbasic_authapi_key_query
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

Create a webhook

Authorizations:
api_key_headerbasic_authapi_key_query
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

This is a 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":
    [
    ]
}

List webhooks

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

Authorizations:
api_key_headerbasic_authapi_key_query
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"
}

Update a webhook

Authorizations:
api_key_headerbasic_authapi_key_query
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

This is a 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 a webhook by id.

Authorizations:
api_key_headerbasic_authapi_key_query
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":
    [
    ]
}

Delete a webhook

Authorizations:
api_key_headerbasic_authapi_key_query
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"
}

Project

Get a project

Retrieves a project by project slug.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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

Get all checkout keys

Returns a sequence of checkout keys for :project.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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',
  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 new checkout key

Creates a new checkout key. This API request is only usable with a user API token.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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

Delete a checkout key

Deletes the checkout key.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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

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.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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

Get a masked environment variable

Returns the masked value of environment variable :name.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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

Delete an environment variable

Deletes the environment variable named :name.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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

Schedule

Get all schedules

Returns all schedules for this project.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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

Creates a schedule and returns the created schedule.

Authorizations:
api_key_headerbasic_authapi_key_query
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.

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

Updates a schedule and returns the updated schedule.

Authorizations:
api_key_headerbasic_authapi_key_query
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 or 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.

Authorizations:
api_key_headerbasic_authapi_key_query
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

Deletes the schedule by id.

Authorizations:
api_key_headerbasic_authapi_key_query
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.