---
title: "CircleCI APIs overview"
description: "Introduction to the CircleCI API versions and their capabilities including a how to choose the right API version for your use case."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-20"
---

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

# CircleCI APIs overview

The CircleCI API enables you to interact with your pipelines, projects, and organizations programmatically. Use the API to retrieve detailed information about users, jobs, workflows, and pipelines. You can also trigger pipelines and manage resources. CircleCI currently supports three API versions, plus a separate API for self-hosted runners:

*   [API v3 Reference](https://circleci.com/docs/api/v3/) (Current)
    
*   [API v2 Reference](https://circleci.com/docs/guides/api/v2/) (Legacy)
    
*   [API v1.1 Reference](https://circleci.com/docs/guides/api/v1/) (Legacy)
    
*   [Runner API Reference](https://circleci.com/docs/reference/runner-api/) (Self-hosted runners)
    

API v3 is not yet available on CircleCI Server. CircleCI Server will support API v3 in a future release.

## API overview

<table><thead><tr><th>Version</th><th>Status</th><th>Key features</th><th>When to use</th></tr></thead><tbody><tr><td>API v3</td><td>Current</td><td><div><div><ul><li><p>UUID-based resource IDs.</p></li><li><p>Opaque cursor pagination.</p></li><li><p>Detailed, consistent error objects.</p></li><li><p>Idempotent operations where applicable.</p></li><li><p>Standard rate-limit headers.</p></li><li><p>Endpoints for workflows, jobs, pipelines, and analytics.</p></li></ul></div></div></td><td><div><div><ul><li><p>All new integrations and scripts.</p></li><li><p>Applications requiring modern API patterns.</p></li><li><p>Projects needing analysis endpoints, deploy management, or notification configuration.</p></li></ul></div></div></td></tr><tr><td>API v2</td><td>Legacy (supported)</td><td><div><div><ul><li><p>Token-based pagination.</p></li><li><p>Pipeline triggering with parameters.</p></li><li><p>Insights endpoints.</p></li><li><p>Workflow and job management.</p></li></ul></div></div></td><td><div><div><ul><li><p>Existing integrations that have not yet migrated to v3.</p></li><li><p>Scripts and tools that depend on v2-specific behavior.</p></li></ul></div></div></td></tr><tr><td>API v1.1</td><td>Legacy (EOL planned)</td><td>Basic pipeline, job, and project endpoints.</td><td><div><div><ul><li><p>Maintaining existing integrations that you have not yet updated.</p></li><li><p>Specific legacy use cases.</p></li></ul></div></div></td></tr><tr><td><a href="https://circleci.com/docs/reference/runner-api/">Runner API</a></td><td>Specialized (separate API)</td><td><div><div><ul><li><p>Hosted at your CircleCI Server hostname, without the <code>runner.</code> prefix</p></li><li><p>Manages and executes self-hosted runner tasks.</p></li><li><p>Supports Circle-Token, Bearer, and resource class token authentication.</p></li></ul></div></div></td><td><div><div><ul><li><p>Managing self-hosted runner resource classes and tasks.</p></li><li><p>Building custom self-hosted runner integrations.</p></li></ul></div></div></td></tr></tbody></table>

CircleCI recommends migrating to API v3 for all new work. API v1.1 is planned for End-Of-Life (EOL); CircleCI will communicate the discontinuation date in the future.

To get started, see the [API V2 Developers Guide](https://circleci.com/docs/guides/server/toolkit/api-developers-guide/) or the [Runner API Reference](https://circleci.com/docs/reference/runner-api/).

## Authentication

All CircleCI API versions use token-based authentication. You need a personal API token to authenticate your requests.

Supported authentication methods

| API version | Bearer Authentication | Circle-Token header | Basic Authentication |
| --- | --- | --- | --- |
| API v3 | **Yes** | **No** | **No** |
| API v2 | **Yes** | **Yes** | **Yes** |
| API v1.1 | **Yes** | **Yes** | **Yes** |
| Runner API | **No** | **Yes** | **Yes** |

Bearer Authentication

Pass the token as a Bearer token in the `Authorization` header.

Circle-Token header

Pass the token in the `Circle-Token` header.

Basic Authentication

Use the token as the username (Base64-encoded).

See the [Managing API Tokens](https://circleci.com/docs/guides/server/toolkit/managing-api-tokens/) guide for information on creating and managing tokens.

The [Runner API](https://circleci.com/docs/reference/runner-api/) accepts these same personal token methods, plus a resource class token used exclusively by self-hosted runner agents. See the Runner API reference for details.

## Next steps

*   Review the [API V2 Developers Guide](https://circleci.com/docs/guides/server/toolkit/api-developers-guide/) for information on the legacy v2 API.
    
*   Explore the [API V3 Reference](https://circleci.com/docs/guides/api/v3/) for complete endpoint documentation.
    
*   See the [Runner API Reference](https://circleci.com/docs/reference/runner-api/) for self-hosted runner endpoints.