API v2 Introduction
The CircleCI API may be used to make API calls to retrieve detailed information about users, jobs, workflows and pipelines. There are currently two supported API versions:
API v2 includes several powerful features (e.g. support for pipelines and pipeline parameters) that are unavailable in API v1.1. It is recommended that CircleCI cloud users migrate their scripts to API v2 stable endpoints as soon as possible.
CircleCI API v1.1 and v2 are supported and generally available. CircleCI expects to eventually End-Of-Life (EOL) API v1.1 in favor of API v2. Further guidance on when CircleCI API v1.1 will be discontinued will be communicated at a future date.
Overview
CircleCI API v2 enables you to use endpoints with several new features that improve the API experience, in addition to optimizing how you use the API for your jobs.
The current categories of the API v2 endpoints are:
- Authentication
- Context
- Insights
- User
- Pipeline
- Job
- Workflow
- Webhook
- Project
- Schedule
Getting started with the API v2
circleci/:slug-remainder
The project slug for GitLab projects can be found by navigating to your project in the CircleCI web app and taking the string from the browser address bar. The slug must be treated as an opaque string and passed in its entirety in API requests. Read the API Developer’s Guide for more details.
The CircleCI API v2 is backwards-compatible with previous API versions in the way it identifies your projects using repository name. For instance, if you want to pull information from CircleCI about the GitHub repository https://github.com/CircleCI-Public/circleci-cli you can refer to that in the CircleCI API as gh/CircleCI-Public/circleci-cli
, which is a “triplet” of the VCS type, the name of your “organization”, and the name of the repository. For the VCS type you can use github
or bitbucket
as well as the shorter forms gh
or bb
, which are now supported in API v2. The organization
is your username or organization name in your version control system.
With API v2, CircleCI is introducing a string representation of the triplet called the project_slug
, which takes the following form:
<vcs_type>/<org_name>/<repo_name>
The project_slug
is included in the payload when pulling information about a project as well as when looking up a pipeline or workflow by ID. The project_slug
can then be used to get information about the project. It is possible in the future the shape of a project_slug
may change, but for GitHub and Bitbucket projects it is currently usable as a human-readable identifier for a given project.
Authentication
The CircleCI API v2 enables users to be authenticated by sending your Personal API token as a HTTP header in the request, with the name Circle-Token
and the token as the value. You can find examples in the API Developer’s Guide.
Triggering a pipeline with parameters example
Here is a simple example using curl
to trigger a pipeline with parameters:
curl -X POST --header "Content-Type: application/json" --header "Circle-Token: $CIRCLE_TOKEN" -d '{
"parameters": {
"myparam": "./myspecialdir",
"myspecialversion": "4.8.2"
}
}' https://circleci.com/api/v2/project/{project_slug}/pipeline
In the above example the project_slug
would take the form :vcs/:org/:project
. For example, the project slug gh/CircleCI-Public/circleci-cli
tells CircleCI
to use the project found in the GitHub organization CircleCI-Public in the repository named circleci-cli
.
IMPORTANT Pipeline parameters are not treated as sensitive data and must not be used for sensitive values (secrets). You can find information on using sensitive data correctly in the Security overview and Contexts guides.
Changes in endpoints
The CircleCI API v2 release includes several new endpoints, and deprecates some others. The sections below list the endpoints added for this release, in addition to the endpoints that have been removed.
For a complete list of all API v2 endpoints, please refer to the API v2 Reference Guide, which contains a detailed description of each individual endpoint, as well as information on required and optional parameters, HTTP status and error codes, and code samples you may use in your workflows.
New endpoints
The table below describes the new endpoints that have been added to the CircleCI API for this updated v2 version.
Endpoint | Description |
---|---|
GET /workflow/:id | Returns an individual workflow based on the id parameter being passed in the request. |
GET /workflow/:id/job | Retrieves all Jobs associated with a specific workflow, based on its unique id . |
GET /project/:project_slug | Retrieves a specific project by its unique slug. |
POST /project/:project_slug/pipeline | Retrieves an individual project by its unique slug. |
GET /pipeline/:id | Retrieves an individual pipeline, based on the id passed in the request. |
GET /pipeline/:id/config | Retrieves the configuration of a specific pipeline. |
GET /project/:project_slug/pipelines/[:filter] | Retrieves the most recent set of pipelines for a Project. |
GET /insights/:project-slug/workflows | Retrieves summary metrics for an individual project’s workflow. |
GET /insights/:project-slug/workflows/:workflow-name | Retrieves recent runs for a workflow. |
GET /insights/:project-slug/workflows/:workflow-name/jobs | Retrieves summary metrics for a project workflow’s jobs. |
GET /insights/:project-slug/workflows/:workflow-name/jobs/:job-name | Retrieves recent runs of a job within a workflow. |
Deprecated endpoints
With API v2, several endpoints from v1 have been deprecated, which are listed in the table below.
Endpoint | Description |
---|---|
POST /project/:vcs-type/:username/:project | This endpoint allowed users to trigger a new build. |
POST /project/:vcs-type/:username/:project/build | This endpoint enabled users to trigger a new build by project. |
GET /recent-builds | This endpoint enabled users to retrieve an array of recent builds. |
Next steps
- Review the API Developer’s Guide for a detailed walkthrough on authenticating as well as example API requests.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.