Documentation structure for LLMs (llms.txt)
CircleCI Logo

CircleCI APIs overview

6 days ago
Cloud Server

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 overview

Version Status Key features When to use

API v3

Current

  • UUID-based resource IDs.

  • Opaque cursor pagination.

  • Detailed, consistent error objects.

  • Idempotent operations where applicable.

  • Standard rate-limit headers.

  • Endpoints for workflows, jobs, pipelines, and analytics.

  • All new integrations and scripts.

  • Applications requiring modern API patterns.

  • Projects needing analysis endpoints, deploy management, or notification configuration.

API v2

Legacy (supported)

  • Token-based pagination.

  • Pipeline triggering with parameters.

  • Insights endpoints.

  • Workflow and job management.

  • Existing integrations that have not yet migrated to v3.

  • Scripts and tools that depend on v2-specific behavior.

API v1.1

Legacy (EOL planned)

Basic pipeline, job, and project endpoints.

  • Maintaining existing integrations that you have not yet updated.

  • Specific legacy use cases.

Runner API

Specialized (separate API)

  • Hosted separately at runner.circleci.com

  • Manages and executes self-hosted runner tasks.

  • Supports Circle-Token, Bearer, and resource class token authentication.

  • Managing self-hosted runner resource classes and tasks.

  • Building custom self-hosted runner integrations.
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 V3 Developers Guide, the API V2 Developers Guide, or the Runner API Reference.

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 guide for information on creating and managing tokens.

The 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