CircleCI currently supports three API versions, plus a separate API for self-hosted runners:
API v3 Reference (Current, Cloud)
API v2 Reference (Legacy, supported; use this on CircleCI Server)
API v1.1 Reference (Legacy, EOL planned)
Self-hosted runner management uses a separate Runner API (hosted at runner.circleci.com). Details are in the official docs under self-hosted runners; start from the CircleCI APIs overview.
Version | Status | When to use |
API v3 | Current (Cloud) | All new Cloud integrations and scripts |
API v2 | Legacy (supported) | Existing Cloud integrations still on v2; all CircleCI Server API work |
API v1.1 | Legacy (EOL planned) | Maintaining older integrations only |
Runner API | Specialized | Self-hosted runner resource classes and tasks |
API v3 is Cloud-only. If you use CircleCI Server, use API v2 (see the API v3 developer’s guide note for Server customers). On Cloud, prefer API v3 for new work. API v1.1 is planned for end of life; CircleCI will communicate the discontinuation date separately. Some older v1.1 endpoints already have published removal dates in the API v1.1 reference.
Full overview: CircleCI APIs overview
Getting started on Cloud with v3: API v3 developer’s guide
Authentication and tokens
Use a personal API token for API requests. Create one from Personal API Tokens (see Managing API tokens). When you create a personal API token, you must set an expiry date of up to one year. CircleCI emails you before the token expires.
Supported auth methods by version:
API version | Bearer ( |
| Basic Auth |
API v3 | Yes (required style) | No | No |
API v2 | Yes (recommended) | Yes | Yes (legacy) |
API v1.1 | Yes (recommended) | Yes | Yes (legacy) |
Notes:
Prefer a personal API token for most scripts and integrations. On API v3, the docs describe Bearer auth with a personal API token or another CircleCI API token.
Project API tokens are documented for API v1 (and status badges). Prefer personal tokens for v2 and v3.
Prefer header auth. Passing the token as a
?circle-token=query parameter is deprecated and should not be used in new scripts.
Quick test (v2 example; on Cloud, use the API v3 developer’s guide for new integrations):
export CIRCLE_TOKEN=<your_personal_api_token> curl https://circleci.com/api/v2/me \ --header "Authorization: Bearer $CIRCLE_TOKEN"
If you use CircleCI Server, replace https://circleci.com with your server hostname and use API v2 (not v3).
API Tips and Tricks
The CircleCI Support team maintains customer solutions below. Prefer API v2/v3 examples and header-based auth when you adapt these scripts. On Server, stick to v2-compatible examples.
Automations
Bash Scripts
Monitoring and Data
More community examples: Discuss threads tagged API