Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

API v2 Introduction

1 month ago3 min read
Cloud
Server v4.x
Server v3.x
On This Page

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

With API v2, CircleCI is introducing a string representation called the project_slug, which is a “triplet” of your version control system (VCS), the name of your organization, and the name of the repository. project_slug takes the following form:

:vcs_type/:org_name/:repo_name

The project_slug is included in the response 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. For GitHub OAuth app 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

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.

EndpointDescription
GET /workflow/:id Returns an individual workflow based on the id parameter being passed in the request.
GET /workflow/:id/jobRetrieves all Jobs associated with a specific workflow, based on its unique id.
GET /project/:project_slugRetrieves a specific project by its unique slug.
POST /project/:project_slug/pipelineRetrieves an individual project by its unique slug.
GET /pipeline/:idRetrieves an individual pipeline, based on the id passed in the request.
GET /pipeline/:id/configRetrieves 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/workflowsRetrieves summary metrics for an individual project’s workflow.
GET /insights/:project-slug/workflows/:workflow-nameRetrieves recent runs for a workflow.
GET /insights/:project-slug/workflows/:workflow-name/jobsRetrieves summary metrics for a project workflow’s jobs.
GET /insights/:project-slug/workflows/:workflow-name/jobs/:job-nameRetrieves 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.

EndpointDescription
POST /project/:vcs-type/:username/:projectThis endpoint allowed users to trigger a new build.
POST /project/:vcs-type/:username/:project/buildThis endpoint enabled users to trigger a new build by project.
GET /recent-buildsThis endpoint enabled users to retrieve an array of recent builds.

Next steps


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.

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.