API v3 is CircleCI’s current API version, and all new API development happens in v3. Every endpoint follows the same conventions, so you can predict how the API works without reading a spec for each one:
- UUID resource IDs instead of project slugs
- Cursor-based pagination
- One error format with structured error objects
- Standard rate limit headers, so tools can back off automatically
What this means for v1 and v2
- Start with v3. It’s built for an improved developer experience and for the use cases developers need today, including AI agents.
- v2 remains supported. If v3 doesn’t cover what you need yet, use v2 with confidence.
- v1 is being replaced by v3. Some v1 endpoints already have v2 or v3 equivalents and will be deprecated first. We’ll announce deprecations of v1 APIs as we remove them or provide alternatives.
- If you use v1, review which endpoints you call. Not all v1 endpoints are affected at the same time.
The CircleCI CLI and MCP server already use API v3, so AI coding agents and scripts that go through them get it automatically.
Some endpoints are marked experimental in the reference and may change. Check each endpoint’s description before you depend on it.
To get started, follow the API v3 developer’s guide or browse the API v3 reference. API v3 is available on CircleCI cloud only. If you use CircleCI server, continue to use API v2.
Related announcements