---
title: "Migrate from API v1/v1.1 to API v3 or v2"
description: "Migrate from deprecated CircleCI API v1 and API v1.1 trigger and rerun endpoints to API v2 or API v3 before the 1 February 2027 removal date."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-11-16"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# 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](#deprecated-endpoints) 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](https://circleci.com/docs/api/v1/#trigger-a-new-job): `POST /api/v1.1/project/<vcs-type>/<username>/<repo>/`
        
    *   [API v1.1](https://circleci.com/docs/api/v1/#trigger-a-new-job-with-a-branch): `POST /api/v1.1/project/<vcs-type>/<username>/<repo>/tree/<branch>`
        
    *   [API v1.1](https://circleci.com/docs/api/v1/#trigger-a-new-job): `POST /api/v1.1/project/<vcs-type>/<username>/<repo>/build`
        
    *   [API v1](https://circleci.com/docs/api/v1/#trigger-a-new-job): `POST /api/v1/project/<username>/<repo>/`
        
    *   [API v1](https://circleci.com/docs/api/v1/#trigger-a-new-job-with-a-branch): `POST /api/v1/project/<username>/<repo>/tree/<branch>`
        
    
*   Migrate to:
    
    *   [API v2](https://circleci.com/docs/api/v2/#tag/Pipeline/operation/triggerPipeline): `POST /api/v2/project/<provider>/<organization>/<project>/pipeline`
        
    

**Using server?** If you are using CircleCI Server, replace `[https://circleci.com](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](https://circleci.com/docs/guides/server/toolkit/managing-api-tokens/) guide.
    
*   The project slug of each project you call. See [Get your project address](#project-addressing).
    
*   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](https://circleci.com/docs/guides/server/toolkit/how-to-find-ids/#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:
    
    ```console
    $ 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](#deprecated-endpoints).
    
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](https://circleci.com/docs/guides/server/orchestrate/pipeline-variables/#pipeline-parameters-in-configuration).
    
*   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](https://circleci.com/docs/guides/server/orchestrate/using-branch-filters/#filter-a-job-with-an-expression) or [Conditional Logic](https://circleci.com/docs/guides/server/orchestrate/workflows/#use-conditional-logic-in-workflows) that checks a pipeline value, such as `pipeline.git.branch`, or a pipeline parameter. See [Pipeline Values](https://circleci.com/docs/guides/server/orchestrate/pipeline-variables/#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](https://circleci.com/docs/guides/server/orchestrate/selecting-a-workflow-to-run-using-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](https://circleci.com/api/v2/project/\<provider\>/\<organization\>/\<project\>/pipeline)`, using the project slug from [Get your project address](#project-addressing). 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:
    
    ```shell
    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:
    
    ```json
    {
      "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:
    
    ```json
    {
      "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](https://jqlang.github.io/jq/) to read the response.

The pipeline ID is `id`:

```shell
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:
    
    ```shell
    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:

```shell
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

*   Review the [API v2 Developers Guide](https://circleci.com/docs/guides/server/toolkit/api-developers-guide/) for details on API v2 endpoints.
    
*   See the [API v2 Reference](https://circleci.com/docs/api/v2/) for complete endpoint documentation.
    
*   See [Managing API Tokens](https://circleci.com/docs/guides/server/toolkit/managing-api-tokens/) for instructions on creating personal API tokens.