Project 10 endpoints

POST /project/{project-slug}/checkout-key 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

operationId: Project_createCheckoutKey

Parameters

Name	In	Required	Type	Description
project-slug	path	required	string	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

application/json

schema ProjectCreateCheckoutKeyRequest

Property	Type	Required
type	string	required

Responses

default

Error response.

201

The checkout key.

POST /project/{project-slug}/checkout-key

DELETE /project/{project-slug}/checkout-key/{fingerprint} Delete a checkout key

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

operationId: Project_deleteCheckoutKeyByFingerprint

Parameters

Name	In	Required	Type	Description
project-slug	path	required	string	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	path	required	string	An SSH key fingerprint.

Responses

default

Error response.

200

A confirmation message.

DELETE /project/{project-slug}/checkout-key/{fingerprint}

GET /project/{project-slug}/checkout-key/{fingerprint} Get a checkout key

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

operationId: Project_getCheckoutKeyByFingerprint

Parameters

Name	In	Required	Type	Description
project-slug	path	required	string	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	path	required	string	An SSH key fingerprint.

Responses

default

Error response.

200

The checkout key.

GET /project/{project-slug}/checkout-key/{fingerprint}

GET /project/{project-slug}/envvar 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.

operationId: Project_listEnvVarValues

Parameters

Name	In	Required	Type	Description
project-slug	path	required	string	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

default

Error response.

200

A sequence of environment variables.

GET /project/{project-slug}/envvar

POST /project/{project-slug}/envvar Create an environment variable

Creates a new environment variable.

operationId: Project_createEnvVar

Parameters

Name	In	Required	Type	Description
project-slug	path	required	string	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

application/json

schema ProjectCreateEnvVarRequest

Property	Type	Required
name	string	required
value	string	required

Responses

default

Error response.

201

The environment variable.

POST /project/{project-slug}/envvar

DELETE /project/{project-slug}/envvar/{name} Delete an environment variable

Deletes the environment variable named :name.

operationId: Project_deleteEnvironmentVariable

Parameters

Name	In	Required	Type	Description
project-slug	path	required	string	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	path	required	string	The name of the environment variable.

Responses

default

Error response.

200

A confirmation message.

DELETE /project/{project-slug}/envvar/{name}

GET /project/{project-slug}/envvar/{name} Get a masked environment variable

Returns the masked value of environment variable :name.

operationId: Project_getMaskedEnvVar

Parameters

Name	In	Required	Type	Description
project-slug	path	required	string	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	path	required	string	The name of the environment variable.

Responses

default

Error response.

200

The environment variable.

GET /project/{project-slug}/envvar/{name}

POST /project/{provider}/{organization}/{project} 🧪 Create a project

[EXPERIMENTAL] Creates a new CircleCI project, and returns a list of the default advanced settings. Can only be called on a repo with a main branch and an existing config.yml file. Not yet available to projects that use GitLab or GitHub App.

operationId: Project_createProjectDefaultSettings

Parameters

Name	In	Required	Type	Description
provider	path	optional	string	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	path	optional	string	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	path	optional	string	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

201

Successful response.

400

Unexpected request body provided.

401

Credentials provided are invalid.

403

None or insufficient credentials provided.

404

Either a branch or a project were not found.

405

Create projects using the API is currently supported for classic Github OAuth and Bitbucket projects only.

429

API rate limits exceeded.

500

Internal server error.

POST /project/{provider}/{organization}/{project}

GET /project/{provider}/{organization}/{project}/settings 🧪 Get project settings

[EXPERIMENTAL] Returns a list of the advanced settings for a CircleCI project, whether enabled (true) or not (false).

operationId: Project_getSettings

Parameters

Name	In	Required	Type	Description
provider	path	optional	string	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	path	optional	string	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	path	optional	string	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

200

Successful response.

401

Credentials provided are invalid.

403

None or insufficient credentials provided.

404

Insufficient credentials for a private project, OR the organization, project, or repository does not exist.

429

API rate limits exceeded.

500

Internal server error.

GET /project/{provider}/{organization}/{project}/settings

PATCH /project/{provider}/{organization}/{project}/settings 🧪 Update project settings

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

operationId: Project_updateSettings

Parameters

Name	In	Required	Type	Description
provider	path	optional	string	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	path	optional	string	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	path	optional	string	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

required

The setting(s) to update, including one or more fields in the JSON object. Note that oss: true will only be set on projects whose underlying repositories are actually open source.

application/json

schema project_settings

Property	Type	Required
advanced	object	optional
└ oss	boolean	optional
└ disable_ssh	boolean	optional
└ build_fork_prs	boolean	optional
└ build_prs_only	boolean	optional
└ setup_workflows	boolean	optional
└ autocancel_builds	boolean	optional
└ set_github_status	boolean	optional
└ pr_only_branch_overrides	array	optional
└ forks_receive_secret_env_vars	boolean	optional
└ write_settings_requires_admin	boolean	optional

Responses

200

Successful response. Always includes the full advanced settings object. Returned even when the provided updates match the existing settings, but can also be returned when oss: true fails to set.

400

Request is malformed, e.g. with improperly encoded JSON

401

Credentials provided are invalid.

403

None or insufficient credentials provided.

404

Insufficient credentials for a private project, OR the organization, project, or repository does not exist.

429

API rate limits exceeded.

500

Internal server error.

PATCH /project/{provider}/{organization}/{project}/settings

Schedule 5 endpoints

GET /project/{project-slug}/schedule Get all schedules

Returns all schedules for this project.

operationId: Schedule_getAllSchedules

Parameters

Name	In	Required	Type	Description
project-slug	path	required	string	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).
page-token	query	optional	string	A token to retrieve the next page of results.

Responses

default

Error response.

200

A sequence of schedules.

GET /project/{project-slug}/schedule

POST /project/{project-slug}/schedule Create a schedule

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

operationId: Schedule_createNewSchedule

Parameters

Name	In	Required	Type	Description
project-slug	path	required	string	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

application/json

schema ScheduleCreateNewScheduleRequest

Property	Type	Required
name	string	required
timetable	object	required
parameters	object	required
description	string	optional
attribution-actor	string	required

Responses

default

Error response.

201

A schedule object.

POST /project/{project-slug}/schedule

DELETE /schedule/{schedule-id} Delete a schedule

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

operationId: Schedule_removeById

Parameters

Name	In	Required	Type	Description
schedule-id	path	required	string	The unique ID of the schedule.

Responses

default

Error response.

200

A confirmation message.

DELETE /schedule/{schedule-id}

GET /schedule/{schedule-id} Get a schedule

Get a schedule by id.

operationId: Schedule_getById

Parameters

Name	In	Required	Type	Description
schedule-id	path	required	string	The unique ID of the schedule.

Responses

default

Error response.

200

A schedule object.

GET /schedule/{schedule-id}

PATCH /schedule/{schedule-id} Update a schedule

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

operationId: Schedule_updateSchedule

Parameters

Name	In	Required	Type	Description
schedule-id	path	required	string	The unique ID of the schedule.

Request Body

application/json

schema ScheduleUpdateScheduleRequest

Property	Type	Required
name	string	optional
timetable	object	optional
└ months	array	optional
└ per-hour	integer	optional
└ days-of-week	array	optional
└ hours-of-day	array	optional
└ days-of-month	array	optional
parameters	object	optional
description	string	optional
attribution-actor	string	optional

Responses

default

Error response.

200

A schedule object.

PATCH /schedule/{schedule-id}

User 3 endpoints

GET /me User Information

Provides information about the user that is currently signed in.

operationId: User_getInformation

Responses

default

Error response.

200

User login information.

GET /me

GET /me/collaborations 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

operationId: User_listCollaborations

Responses

default

Error response.

200

Collaborations

GET /me/collaborations

GET /user/{id} User Information

Provides information about the user with the given ID.

operationId: User_getUserInformation

Parameters

Name	In	Required	Type	Description
id	path	required	string	The unique ID of the user.

Responses

default

Error response.

200

User login information.

GET /user/{id}

Webhook 5 endpoints

GET /webhook List webhooks

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

operationId: Webhook_listMatchingScope

Parameters

Name	In	Required	Type	Description
scope-id	query	required	string	ID of the scope being used (at the moment, only project ID is supported)
scope-type	query	required	string	Type of the scope being used

Responses

default

Error response.

200

A list of webhooks

GET /webhook

POST /webhook Create an outbound webhook

Creates an outbound webhook.

operationId: Webhook_createOutboundWebhook

Request Body

application/json

schema WebhookCreateOutboundWebhookRequest

Property	Type	Required
url	string	required
name	string	required
scope	object	required
└ id	string	required
└ type	string	required
events	array	required
verify-tls	boolean	required
signing-secret	string	required

Responses

default

Error response.

201

A webhook

POST /webhook

DELETE /webhook/{webhook-id} Delete an outbound webhook

Deletes an outbound webhook

operationId: Webhook_deleteOutboundWebhook

Parameters

Name	In	Required	Type	Description
webhook-id	path	required	string	ID of the webhook (UUID)

Responses

default

Error response.

200

A confirmation message

DELETE /webhook/{webhook-id}

GET /webhook/{webhook-id} Get a webhook

Get an outbound webhook by id.

operationId: Webhook_getById

Parameters

Name	In	Required	Type	Description
webhook-id	path	required	string	ID of the webhook (UUID)

Responses

default

Error response.

200

A webhook

GET /webhook/{webhook-id}

PUT /webhook/{webhook-id} Update an outbound webhook

Updates an outbound webhook.

operationId: Webhook_updateOutboundWebhook

Parameters

Name	In	Required	Type	Description
webhook-id	path	required	string	ID of the webhook (UUID)

Request Body

application/json

schema WebhookUpdateOutboundWebhookRequest

Property	Type	Required
url	string	optional
name	string	optional
events	array	optional
verify-tls	boolean	optional
signing-secret	string	optional

Responses

default

Error response.

200

A webhook

PUT /webhook/{webhook-id}

Workflow 5 endpoints

GET /workflow/{id} Get a workflow

Returns summary fields of a workflow by ID.

operationId: Workflow_getById

Parameters

Name	In	Required	Type	Description
id	path	required	string	The unique ID of the workflow.

Responses

default

Error response.

200

A workflow object.

GET /workflow/{id}

POST /workflow/{id}/approve/{approval_request_id} Approve a job

Approves a pending approval job in a workflow.

operationId: Workflow_approveJob

Parameters

Name	In	Required	Type	Description
approval_request_id	path	required	string	The ID of the job being approved.
id	path	required	string	The unique ID of the workflow.

Responses

default

Error response.

202

A confirmation message.

POST /workflow/{id}/approve/{approval_request_id}

POST /workflow/{id}/cancel Cancel a workflow

Cancels a running workflow.

operationId: Workflow_cancelWorkflow

Parameters

Name	In	Required	Type	Description
id	path	required	string	The unique ID of the workflow.

Responses

default

Error response.

202

A confirmation message.

POST /workflow/{id}/cancel

GET /workflow/{id}/job Get a workflow's jobs

Returns a sequence of jobs for a workflow.

operationId: Workflow_getJobs

Parameters

Name	In	Required	Type	Description
id	path	required	string	The unique ID of the workflow.

Responses

default

Error response.

200

A paginated sequence of jobs.

GET /workflow/{id}/job

POST /workflow/{id}/rerun Rerun a workflow

Reruns a workflow.

operationId: Workflow_rerunWorkflow

Parameters

Name	In	Required	Type	Description
id	path	required	string	The unique ID of the workflow.

Request Body

application/json

schema WorkflowRerunWorkflowRequest

Property	Type	Required
jobs	array	optional
enable_ssh	boolean	optional
from_failed	boolean	optional
sparse_tree	boolean	optional

Responses

default

Error response.

202

A confirmation message.

POST /workflow/{id}/rerun