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 v2 to replace these calls. API v3 is not available on CircleCI 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. The API v1 and API v1.1 retry and ssh endpoints do not exist on CircleCI Server, so you have only trigger calls to migrate.

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 v2: POST /api/v2/project/<provider>/<organization>/<project>/pipeline

Using server? If you are using CircleCI Server, replace https://circleci.com with your server hostname when interacting with the CircleCI API.

Prerequisites

Have the following ready before you start step 1:

  • A CircleCI personal API token. API v2 does 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 project slug of each project you call. See Get your project address.

  • 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 v2 identifies a project by its project slug, which you put in the URL of each request. To find it, see 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.

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.

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.

  • Send either branch or tag, not both.

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

Replace trigger calls using API v2

  1. Replace the URL of the call with https://circleci.com/api/v2/project/<provider>/<organization>/<project>/pipeline, 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 the branch in branch. To trigger a tag, send tag instead:

    curl --request POST \
      "https://circleci.com/api/v2/project/<provider>/<organization>/<project>/pipeline" \
      --header "Authorization: Bearer $CIRCLE_TOKEN" \
      --header "Content-Type: application/json" \
      --data '{"branch": "main"}'
  4. If the call passed build_parameters, add each value to a parameters object in the request body:

    {
      "branch": "main",
      "parameters": {
        "<parameter-name>": "<parameter-value>"
      }
    }
  5. Send the request. The response contains the pipeline id and number. Save both. 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 3:

    {
      "id": "<pipeline-id>",
      "number": 1,
      "state": "pending",
      "created_at": "2020-01-01T15:32:36.605Z"
    }

3. 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 returns a pipeline 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.

The pipeline ID is id:

PIPELINE_ID=$(curl --silent --request POST \
  "https://circleci.com/api/v2/project/<provider>/<organization>/<project>/pipeline" \
  --header "Authorization: Bearer $CIRCLE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"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 does not return a URL.

  1. Take the pipeline number from the trigger response.

  2. Get the 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)"'
  3. Use the pipeline number and the workflow ID to find the workflow in the CircleCI web app.

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

Next steps