Migrate from API v1/v1.1 to API v3 or v2
On 1 February 2027, CircleCI removes nine API v1 and API v1.1 endpoints. These endpoints trigger and rerun builds. See Deprecated endpoints and their replacements for the list. Until then, the deprecated endpoints return Deprecation and Sunset response headers. After that date, requests to these endpoints return HTTP 410 Gone. This guide shows you how to find those calls in your code and replace each one.
Use API v3 to replace these calls. API v2 remains supported if API v3 does not cover your needs.
API v3 is available on CircleCI Cloud only. CircleCI Server customers use API v2, and the API v2 steps in this guide apply to both Cloud and Server.
Deprecated endpoints and their replacements
This change applies to both CircleCI Cloud and CircleCI Server. Each entry lists the deprecated endpoints and the endpoints to migrate to.
All other API v1 and API v1.1 endpoints, including every GET endpoint, are not affected.
API v2 and API v3 endpoints are not affected.
- Trigger a pipeline run
-
-
Deprecated:
-
API v1.1:
POST /api/v1.1/project/<vcs-type>/<username>/<repo>/ -
API v1.1:
POST /api/v1.1/project/<vcs-type>/<username>/<repo>/tree/<branch> -
API v1.1:
POST /api/v1.1/project/<vcs-type>/<username>/<repo>/build -
API v1:
POST /api/v1/project/<username>/<repo>/ -
API v1:
POST /api/v1/project/<username>/<repo>/tree/<branch>
-
-
Migrate to:
-
- Rerun a workflow
- Rerun a workflow with SSH enabled
-
-
Deprecated:
-
Migrate to:
-
Prerequisites
Have the following ready before you start step 1:
-
A CircleCI personal API token. API v3 and API v2 do not support project API tokens, so create a personal API token if you use a project token today. See the Managing API Tokens guide.
-
The address of each project you call: the project ID for API v3 and the project slug for API v2. See Get your project address.
-
If you trigger pipeline runs, the pipeline definition ID for each project. See Get your pipeline definition ID.
-
Access to edit the scripts, tools, and integrations that call the deprecated endpoints.
Know where to send your token
In every call you change, send your personal API token in the Authorization: Bearer header. API v2 also accepts the Circle-Token header and HTTP basic authentication.
Get your project address
API v3 identifies a project by its project ID. API v2 identifies a project by its project slug, which you put in the URL of each request. To find them, see Find a Project ID and Find a Project Slug. In a project slug, gh and github both mean GitHub, and bb and bitbucket both mean Bitbucket. API v2 accepts either form.
Get your pipeline definition ID
A pipeline definition tells CircleCI which repository and config file to use for a pipeline. A project can have more than one, so a trigger request names the one to run. You need this ID only if you trigger pipeline runs.
To find it, see Find a Pipeline Definition ID.
1. Find your API v1 and v1.1 calls
Search your CI scripts, automation tooling, and third-party integrations for calls to the deprecated endpoints.
-
In each repository that calls the API, run:
$ grep -rE "api/v1(\.1)?/project" . -
Check these places for calls the search misses:
-
Shell scripts and
Makefilebuild files. -
CI configuration files such as
.circleci/config.ymland.github/workflows/. -
Internal tooling, deployment scripts, and scheduled jobs.
-
Third-party integrations and webhook consumers that call back into CircleCI.
-
-
For each match, check whether the HTTP method is
POSTand whether the path matches one of the deprecated endpoints listed in Deprecated endpoints and their replacements. -
Make a list of the calls you find, grouped by what they do. The steps that follow depend on the group:
-
Calls that trigger a build, such as
/,/build, and/tree/<branch>: do step 2. -
Calls that rerun a build with
/retry: do step 3. -
Calls that rerun a build with SSH using
/ssh: do step 4.
-
2. Replace your trigger calls
Do this step if you call POST …/, POST …/build, or POST …/tree/<branch>. Otherwise, go to step 3.
Before you change a trigger call, be aware of the following:
-
The branch moves from the URL path (
/tree/<branch>) into the request body. -
configandcheckoutmust use the same reference type. Usebranchin both ortagin both. Mixing them returns an error. In API v3, they must also match when both come from the same repository. -
revisionhas no replacement. API v2 takes a branch or a tag, not a commit. -
Environment variables set through
build_parametershave no direct replacement. For each value, declare a pipeline parameter in your config, then pass the values inparameters. See Pipeline Values and Parameters. -
API v2 and API v3 triggers have no equivalent of the
jobparameter, which ran a single job by name. To run only some jobs, use an Expression-Based Job Filter or Conditional Logic that checks a pipeline value, such aspipeline.git.branch, or a pipeline parameter. See Pipeline Values for the values you can check. To use a pipeline parameter, declare it in your config and send its value inparameters. See Select a Workflow With Pipeline Parameters for an example. -
A pipeline parameter that your config does not declare is not rejected when you trigger. The request returns a success response, and the pipeline then fails with the error
Unexpected argument(s): <parameter-name>. -
If your project uses GitHub OAuth or Bitbucket OAuth, add your project ID to the URL as the
filter[project_id]query parameter. API v3 derives the pipeline definition of an OAuth project from the project, so it can find the definition only with the project ID. Without it, the request returns404 Not Found. A project that uses the GitHub App does not need the parameter. A project ID that does not own the pipeline definition also returns404 Not Found. To check your integration type, find your organization slug. See Find an Organization Slug for the web app and API steps. The slug starts withgh/orgithub/for GitHub OAuth. It starts withbb/orbitbucket/for Bitbucket OAuth. It starts withcircleci/for the GitHub App.
Replace trigger calls using API v3
-
Replace the URL of the call with
https://circleci.com/api/v3/runs. If your project uses GitHub OAuth or Bitbucket OAuth, add?filter[project_id]=<project-id>to the URL, using the project ID from Get your project address. The method staysPOST. -
Send your personal API token in the
Authorization: Bearerheader. Remove anycircle-tokenquery parameter or basic authentication from the call. -
Replace the request body. Send your pipeline definition ID in
references.pipeline.id, and send the branch inconfig.branchandcheckout.branch. To trigger a tag, sendconfig.tagandcheckout.taginstead:curl --request POST https://circleci.com/api/v3/runs \ --header "Authorization: Bearer $CIRCLE_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "data": { "attributes": { "config": { "branch": "main" }, "checkout": { "branch": "main" } }, "references": { "pipeline": { "id": "<pipeline-definition-id>" } } } }' -
If the call passed
build_parameters, add each value to aparametersobject inattributes:"attributes": { "config": { "branch": "main" }, "checkout": { "branch": "main" }, "parameters": { "<parameter-name>": "<parameter-value>" } } -
Send the request. The response contains the run ID in
data.id. Save it, because you need it to find the run’s workflows in step 3 and to check its status in step 5. The response does not include a pipeline number or a URL. Step 5 shows how to get them:{ "data": { "id": "<run-id>", "attributes": { "created_at": "2020-01-01T15:32:36.605Z" }, "references": { "pipeline": { "id": "<pipeline-definition-id>" }, "project": { "id": "<project-id>" }, "user": { "id": "<user-id>" } } } }
Replace trigger calls using API v2
-
Replace the URL of the call with
https://circleci.com/api/v2/project/<provider>/<organization>/<project>/pipeline/run, using the project slug from Get your project address. The method staysPOST. -
Send your personal API token in the
Authorization: Bearerheader. Remove anycircle-tokenquery parameter or basic authentication from the call. -
Replace the request body. Send your pipeline definition ID in
definition_id, and send the branch inconfig.branchandcheckout.branch. To trigger a tag, sendconfig.tagandcheckout.taginstead:curl --request POST \ "https://circleci.com/api/v2/project/<provider>/<organization>/<project>/pipeline/run" \ --header "Authorization: Bearer $CIRCLE_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "definition_id": "<pipeline-definition-id>", "config": { "branch": "main" }, "checkout": { "branch": "main" } }' -
If the call passed
build_parameters, add each value to aparametersobject in the request body:{ "definition_id": "<pipeline-definition-id>", "config": { "branch": "main" }, "checkout": { "branch": "main" }, "parameters": { "<parameter-name>": "<parameter-value>" } } -
Send the request. The response contains the pipeline
idandnumber. Save both. You need theidto find the pipeline’s workflows in step 3. API v1.1 returned abuild_urland API v2 does not, so you use thenumberto build the link to the pipeline yourself in step 5:{ "id": "<pipeline-id>", "number": 1, "state": "pending", "created_at": "2020-01-01T15:32:36.605Z" }
3. Replace your rerun calls
Do this step if you call POST …/<build-num>/retry. Otherwise, go to step 4.
Before you change a rerun call, be aware of the following:
-
Every rerun needs a workflow ID, not a build number.
-
A rerun creates a new workflow with a new ID. Save the new ID if you track the result.
Get the workflow ID
API v1 and API v1.1 identified a build by its build number. API v2 and API v3 identify it by an ID, so use the ID that the trigger response returned in step 2. List the workflows with the call that matches the API version you triggered with:
-
If you triggered with API v3, list the workflows for the run, using the run ID from the trigger response:
curl -g "https://circleci.com/api/v3/workflows?filter[run_id]=<run-id>" \ --header "Authorization: Bearer $CIRCLE_TOKEN" -
If you triggered with API v2, list the workflows for the pipeline, using the pipeline ID from the trigger response:
curl "https://circleci.com/api/v2/pipeline/<pipeline-id>/workflow" \ --header "Authorization: Bearer $CIRCLE_TOKEN"
Then copy the id of the workflow you want to rerun.
Replace rerun calls using API v3
-
Replace the URL of the call with
https://circleci.com/api/v3/workflows/<workflow-id>/rerun. The method staysPOST. -
Send your personal API token in the
Authorization: Bearerheader. Remove anycircle-tokenquery parameter or basic authentication from the call. -
To rerun all jobs in the workflow, send an empty request body:
curl --request POST \ "https://circleci.com/api/v3/workflows/<workflow-id>/rerun" \ --header "Authorization: Bearer $CIRCLE_TOKEN" \ --header "Content-Type: application/json" \ --data '{}' -
To rerun only failed jobs, send
is_from_failedset totrue:curl --request POST \ "https://circleci.com/api/v3/workflows/<workflow-id>/rerun" \ --header "Authorization: Bearer $CIRCLE_TOKEN" \ --header "Content-Type: application/json" \ --data '{"is_from_failed": true}' -
Send the request. The response contains the ID of the new workflow in
data.id. Save it if you track the result.
Replace rerun calls using API v2
-
Replace the URL of the call with
https://circleci.com/api/v2/workflow/<workflow-id>/rerun. The method staysPOST. -
Send your personal API token in the
Authorization: Bearerheader. Remove anycircle-tokenquery parameter or basic authentication from the call. -
To rerun all jobs in the workflow, send an empty request body:
curl --request POST \ "https://circleci.com/api/v2/workflow/<workflow-id>/rerun" \ --header "Authorization: Bearer $CIRCLE_TOKEN" \ --header "Content-Type: application/json" \ --data '{}' -
To rerun only failed jobs, send
from_failedset totrue:curl --request POST \ "https://circleci.com/api/v2/workflow/<workflow-id>/rerun" \ --header "Authorization: Bearer $CIRCLE_TOKEN" \ --header "Content-Type: application/json" \ --data '{"from_failed": true}' -
Send the request. The response contains the ID of the new workflow in
workflow_id. Save it if you track the result.
4. Replace your rerun-with-SSH calls
Do this step if you call POST …/<build-num>/ssh. Otherwise, go to step 5.
Before you change an SSH rerun call, be aware of the following:
-
An SSH rerun must name the jobs to rerun, so you need job IDs as well as the workflow ID.
-
You cannot combine
enable_ssh(API v2) oris_ssh_enabled(API v3) with the from-failed option. A request that sends both returns an error.
Replace SSH rerun calls using API v3
-
Get the workflow ID. See Get the workflow ID.
-
List the jobs in the workflow and copy the
idof each job to rerun:curl -g "https://circleci.com/api/v3/jobs?filter[workflow_id]=<workflow-id>" \ --header "Authorization: Bearer $CIRCLE_TOKEN" -
Replace the URL of the call with
https://circleci.com/api/v3/workflows/<workflow-id>/rerun, send your personal API token in theAuthorization: Bearerheader, and sendis_ssh_enabledset totruewith the job IDs injobs:curl --request POST \ "https://circleci.com/api/v3/workflows/<workflow-id>/rerun" \ --header "Authorization: Bearer $CIRCLE_TOKEN" \ --header "Content-Type: application/json" \ --data '{"is_ssh_enabled": true, "jobs": ["<job-id>"]}' -
Send the request. The response contains the ID of the new workflow in
data.id.
Replace SSH rerun calls using API v2
-
Get the workflow ID. See Get the workflow ID.
-
List the jobs in the workflow and copy the
idof each job to rerun:curl "https://circleci.com/api/v2/workflow/<workflow-id>/job" \ --header "Authorization: Bearer $CIRCLE_TOKEN" -
Replace the URL of the call with
https://circleci.com/api/v2/workflow/<workflow-id>/rerun, send your personal API token in theAuthorization: Bearerheader, and sendenable_sshset totruewith the job IDs injobs:curl --request POST \ "https://circleci.com/api/v2/workflow/<workflow-id>/rerun" \ --header "Authorization: Bearer $CIRCLE_TOKEN" \ --header "Content-Type: application/json" \ --data '{"enable_ssh": true, "jobs": ["<job-id>"]}' -
Send the request. The response contains the ID of the new workflow in
workflow_id.
5. Update how you handle responses
Do this step if any of your code reads the response of a deprecated call.
API v1 and API v1.1 triggered a job and returned a build summary with fields such as build_num, build_url, and status.
API v2 and API v3 return a pipeline or run object instead, so those fields no longer exist.
Update each part of your code that reads one of them.
Replace build numbers
If your code reads build_num from the trigger response, read the ID instead. Use it to look up the workflows and their status. The examples use jq to read the response.
-
For API v3, read the run ID from
data.idin the response from step 2. The response has no equivalent ofbuild_num. To get the pipeline number, which the web app uses in its URLs, see Replace build URLs. -
For API v2, the pipeline ID is
id:PIPELINE_ID=$(curl --silent --request POST \ "https://circleci.com/api/v2/project/<provider>/<organization>/<project>/pipeline/run" \ --header "Authorization: Bearer $CIRCLE_TOKEN" \ --header "Content-Type: application/json" \ --data '{"definition_id": "<pipeline-definition-id>", "config": {"branch": "main"}, "checkout": {"branch": "main"}}' \ | jq --raw-output '.id')
Replace build URLs
If your code reads build_url from the trigger response, build the link yourself.
API v2 and API v3 do not return a URL.
-
Build the link to the workflow in the CircleCI web app from the following pattern. In this URL, use
githubforghandbitbucketforbb:https://app.circleci.com/pipelines/<provider>/<organization>/<project>/<pipeline-number>/workflows/<workflow-id>For example:
https://app.circleci.com/pipelines/github/my-org/my-repo/130/workflows/fda08377-fe7e-46b1-8992-3a7aaecac9c3 -
Take
<organization>and<project>from the names in your old call, which are<username>and<repo>in the API v1.1 URL. -
Take
<pipeline-number>from thenumberfield of the API v2 trigger response. -
Get
<workflow-id>by listing the workflows in the pipeline:curl --silent "https://circleci.com/api/v2/pipeline/$PIPELINE_ID/workflow" \ --header "Authorization: Bearer $CIRCLE_TOKEN" \ | jq --raw-output '.items[] | "\(.name): \(.id)"'For API v3, get the pipeline number from
GET /api/v3/runs/<run-id>, where it is indata.attributes.number. A new run is not readable at the moment you create it. If the request returns 404 withRun not found, wait and send it again. Get the workflow IDs fromGET /api/v3/workflows?filter[run_id]=<run-id>.
Replace status polling
If your code reads status from the trigger response, poll the workflow instead. In API v2, GET /api/v2/workflow/<workflow-id> returns a status field:
curl --silent "https://circleci.com/api/v2/workflow/<workflow-id>" \
--header "Authorization: Bearer $CIRCLE_TOKEN" \
| jq --raw-output '.status'
Keep polling while the status is one of the following:
-
running -
failing -
on_hold: The workflow is waiting for approval. It does not finish until someone approves or cancels it.
The workflow has finished when the status is one of the following:
-
success -
failed -
error -
canceled -
not_run -
unauthorized
In API v3, poll the run. GET /api/v3/runs/<run-id> returns the state of the run in two fields:
curl --silent "https://circleci.com/api/v3/runs/<run-id>" \
--header "Authorization: Bearer $CIRCLE_TOKEN" \
| jq '.data.attributes | {phase, current_outcome}'
-
phaseisqueued,started, orended. Keep polling until it isended. -
current_outcomeisnulluntil the run has a result. After that, it is the result so far, and it can change after the run ends if you rerun a workflow. The possible values are:-
succeeded -
failed -
canceled -
errored -
not_run -
unauthorized
-
Get the build number, URL, and status with API v3
The following script triggers a run and prints the equivalent of the build_num, build_url, and status fields that API v1.1 returned. It combines the calls from the previous sections. If your project uses GitHub OAuth or Bitbucket OAuth, keep the filter[project_id] parameter. Otherwise, remove it. Replace each value in angle brackets.
#!/bin/bash
AUTH="Authorization: Bearer $CIRCLE_TOKEN"
BASE=https://circleci.com/api/v3
# Trigger the run and save its ID.
RUN_ID=$(curl --silent --globoff --request POST \
"$BASE/runs?filter[project_id]=<project-id>" \
--header "$AUTH" \
--header "Content-Type: application/json" \
--data '{"data": {"attributes": {"config": {"branch": "main"}, "checkout": {"branch": "main"}}, "references": {"pipeline": {"id": "<pipeline-definition-id>"}}}}' \
| jq --raw-output '.data.id')
# A new run is not readable at the moment you create it, so retry until it is.
for attempt in 1 2 3 4 5; do
RUN=$(curl --silent "$BASE/runs/$RUN_ID" --header "$AUTH")
NUMBER=$(echo "$RUN" | jq --raw-output '.data.attributes.number // empty')
[ -n "$NUMBER" ] && break
sleep 2
done
# Get the workflow ID to build the URL.
WORKFLOW_ID=$(curl --silent --globoff "$BASE/workflows?filter[run_id]=$RUN_ID" \
--header "$AUTH" | jq --raw-output '.data[0].id')
echo "build_num: $NUMBER"
echo "build_url: https://app.circleci.com/pipelines/<provider>/<organization>/<project>/$NUMBER/workflows/$WORKFLOW_ID"
echo "status: $(echo "$RUN" | jq --compact-output '.data.attributes | {phase, current_outcome}')"
Next steps
-
Review the API v3 Developers Guide for a full walkthrough of API v3.
-
Review the API v2 Developers Guide for details on API v2 endpoints.
-
See the API v2 Reference and API v3 Reference for complete endpoint documentation.
-
See Managing API Tokens for instructions on creating personal API tokens.