Documentation structure for LLMs (llms.txt)

Migrate from API v1/v1.1 to API v3 or v2

Cloud Server

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:

    • API v3: POST /api/v3/runs

    • API v2: POST /api/v2/project/<provider>/<organization>/<project>/pipeline/run

Rerun a workflow
  • Deprecated:

    • API v1.1: POST /api/v1.1/project/<vcs-type>/<username>/<repo>/<build-num>/retry

    • API v1: POST /api/v1/project/<username>/<repo>/<build-num>/retry

  • Migrate to:

    • API v3: POST /api/v3/workflows/<workflow-id>/rerun

    • API v2: POST /api/v2/workflow/<workflow-id>/rerun

Rerun a workflow with SSH enabled
  • Deprecated:

    • API v1.1: POST /api/v1.1/project/<vcs-type>/<username>/<repo>/<build-num>/ssh

    • API v1: POST /api/v1/project/<username>/<repo>/<build-num>/ssh

  • Migrate to:

    • API v3: POST /api/v3/workflows/<workflow-id>/rerun with "is_ssh_enabled": true and a "jobs" array.

    • API v2: POST /api/v2/workflow/<workflow-id>/rerun with "enable_ssh": true and a "jobs" array.

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.

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.

  1. In each repository that calls the API, run:

    $ grep -rE "api/v1(\.1)?/project" .
  2. Check these places for calls the search misses:

    • Shell scripts and Makefile build files.

    • CI configuration files such as .circleci/config.yml and .github/workflows/.

    • Internal tooling, deployment scripts, and scheduled jobs.

    • Third-party integrations and webhook consumers that call back into CircleCI.

  3. For each match, check whether the HTTP method is POST and whether the path matches one of the deprecated endpoints listed in Deprecated endpoints and their replacements.

  4. 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.

  • config and checkout must use the same reference type. Use branch in both or tag in both. Mixing them returns an error. In API v3, they must also match when both come from the same repository.

  • revision has no replacement. API v2 takes a branch or a tag, not a commit.

  • Environment variables set through build_parameters have no direct replacement. For each value, declare a pipeline parameter in your config, then pass the values in parameters. See Pipeline Values and Parameters.

  • API v2 and API v3 triggers have no equivalent of the job parameter, 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 as pipeline.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 in parameters. 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 returns 404 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 returns 404 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 with gh/ or github/ for GitHub OAuth. It starts with bb/ or bitbucket/ for Bitbucket OAuth. It starts with circleci/ for the GitHub App.

Replace trigger calls using API v3

  1. 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 stays POST.

  2. Send your personal API token in the Authorization: Bearer header. Remove any circle-token query parameter or basic authentication from the call.

  3. Replace the request body. Send your pipeline definition ID in references.pipeline.id, and send the branch in config.branch and checkout.branch. To trigger a tag, send config.tag and checkout.tag instead:

    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>" }
          }
        }
      }'
  4. If the call passed build_parameters, add each value to a parameters object in attributes:

    "attributes": {
      "config": { "branch": "main" },
      "checkout": { "branch": "main" },
      "parameters": {
        "<parameter-name>": "<parameter-value>"
      }
    }
  5. 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

  1. 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 stays POST.

  2. Send your personal API token in the Authorization: Bearer header. Remove any circle-token query parameter or basic authentication from the call.

  3. Replace the request body. Send your pipeline definition ID in definition_id, and send the branch in config.branch and checkout.branch. To trigger a tag, send config.tag and checkout.tag instead:

    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" }
      }'
  4. If the call passed build_parameters, add each value to a parameters object in the request body:

    {
      "definition_id": "<pipeline-definition-id>",
      "config": { "branch": "main" },
      "checkout": { "branch": "main" },
      "parameters": {
        "<parameter-name>": "<parameter-value>"
      }
    }
  5. Send the request. The response contains the pipeline id and number. Save both. You need the id to find the pipeline’s workflows in step 3. API v1.1 returned a build_url and API v2 does not, so you use the number to 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

  1. Replace the URL of the call with https://circleci.com/api/v3/workflows/<workflow-id>/rerun. The method stays POST.

  2. Send your personal API token in the Authorization: Bearer header. Remove any circle-token query parameter or basic authentication from the call.

  3. 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 '{}'
  4. To rerun only failed jobs, send is_from_failed set to true:

    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}'
  5. 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

  1. Replace the URL of the call with https://circleci.com/api/v2/workflow/<workflow-id>/rerun. The method stays POST.

  2. Send your personal API token in the Authorization: Bearer header. Remove any circle-token query parameter or basic authentication from the call.

  3. 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 '{}'
  4. To rerun only failed jobs, send from_failed set to true:

    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}'
  5. 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) or is_ssh_enabled (API v3) with the from-failed option. A request that sends both returns an error.

Replace SSH rerun calls using API v3

  1. Get the workflow ID. See Get the workflow ID.

  2. List the jobs in the workflow and copy the id of each job to rerun:

    curl -g "https://circleci.com/api/v3/jobs?filter[workflow_id]=<workflow-id>" \
      --header "Authorization: Bearer $CIRCLE_TOKEN"
  3. Replace the URL of the call with https://circleci.com/api/v3/workflows/<workflow-id>/rerun, send your personal API token in the Authorization: Bearer header, and send is_ssh_enabled set to true with the job IDs in jobs:

    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>"]}'
  4. Send the request. The response contains the ID of the new workflow in data.id.

Replace SSH rerun calls using API v2

  1. Get the workflow ID. See Get the workflow ID.

  2. List the jobs in the workflow and copy the id of each job to rerun:

    curl "https://circleci.com/api/v2/workflow/<workflow-id>/job" \
      --header "Authorization: Bearer $CIRCLE_TOKEN"
  3. Replace the URL of the call with https://circleci.com/api/v2/workflow/<workflow-id>/rerun, send your personal API token in the Authorization: Bearer header, and send enable_ssh set to true with the job IDs in jobs:

    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>"]}'
  4. 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.id in the response from step 2. The response has no equivalent of build_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.

  1. Build the link to the workflow in the CircleCI web app from the following pattern. In this URL, use github for gh and bitbucket for bb:

    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
  2. Take <organization> and <project> from the names in your old call, which are <username> and <repo> in the API v1.1 URL.

  3. Take <pipeline-number> from the number field of the API v2 trigger response.

  4. 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 in data.attributes.number. A new run is not readable at the moment you create it. If the request returns 404 with Run not found, wait and send it again. Get the workflow IDs from GET /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}'
  • phase is queued, started, or ended. Keep polling until it is ended.

  • current_outcome is null until 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