A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The CircleCI API is how an app or AI agent works with a CircleCI account: triggering a pipeline, reading the workflows and jobs inside it, canceling or rerunning a workflow, and managing the contexts and environment variables that builds use. Access is granted through a personal API token sent in a request header, and that token inherits the user's own access, so an agent can reach whatever projects and organizations that person can. CircleCI can also push an event to a webhook when a workflow or job finishes.
How an app or AI agent connects to CircleCI determines what it can reach. There are two routes, the REST API and a first-party MCP server, and both are governed by the API token behind them.
The v2 REST API answers at https://circleci.com/api/v2. It covers pipelines, workflows, jobs, projects, contexts, environment variables, insights, and webhooks, with the version named in the path.
CircleCI's first-party MCP server lets an AI assistant call CircleCI through the Model Context Protocol, for tasks like finding a failed pipeline and pulling its logs. It is the open-source @circleci/mcp-server-circleci, runs locally, and uses the same personal API token as the REST API. The source is at github.com/CircleCI-Public/mcp-server-circleci.
Webhooks deliver workflow-completed and job-completed events to a receiver URL registered on a project, and a signature header on each delivery lets the receiver confirm it came from CircleCI.
A personal API token is the only credential the v2 API accepts. It is sent in the Circle-Token header, or as the HTTP Basic Auth username, and inherits the full read and write access of the user who created it across every project and organization they can reach. It has no scopes and cannot be edited after creation.
A project API token is scoped to one project with a Status, Read Only, or Admin level, but it works only with the older v1 API and cannot call any v2 endpoint. It is listed here so it is not mistaken for a way to scope v2 access.
The CircleCI API is organized around the building blocks of a pipeline run: pipelines, the workflows inside them, the jobs inside those, plus the projects, contexts, and environment variables that supply them. Each area has its own methods, and some reach secrets that others never touch.
Trigger a pipeline, continue one from its setup phase, list a project's pipelines, and read a pipeline's details, config, values, and workflows.
Read a workflow, list its jobs, and cancel or rerun it.
Read a job's details and cancel a running job.
Read a project's details, create a project, and manage its checkout keys.
List, create, read, and delete contexts, and add, list, or remove the environment variables they hold.
List, create, read, and delete a project's environment variables.
Read aggregated metrics for an organization, a project, its workflows and jobs, and its flaky tests.
List, create, read, update, and delete the outbound webhooks registered on a project.
Read the authenticated user and their collaborations.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
PipelinesTrigger a pipeline, continue one from its setup phase, list a project's pipelines, and read a pipeline's details, config, values, and workflows.6 | ||||||
| POST | /project/{project-slug}/pipeline | Trigger a new pipeline on a project. | write | Pipeline: trigger | Current | |
Starts a real run that can deploy or change live systems. Needs a personal API token; the token's user must have access to the project. CircleCI has no per-endpoint scopes. Acts onpipeline Permission (capability) Pipeline: triggerVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /pipeline/continue | Continue a pipeline from its setup phase, used by dynamic configuration. | write | Pipeline: trigger | Current | |
Uses a continuation key issued during a setup workflow rather than starting a new pipeline from scratch. Needs a personal API token. Acts onpipeline Permission (capability) Pipeline: triggerVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /project/{project-slug}/pipeline | List all pipelines for a project. | read | Pipeline: read | Current | |
Paginated through next_page_token. Needs a personal API token whose user can see the project. Acts onpipeline Permission (capability) Pipeline: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pipeline/{pipeline-id} | Get a pipeline by its ID. | read | Pipeline: read | Current | |
Needs a personal API token whose user can see the project. Acts onpipeline Permission (capability) Pipeline: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pipeline/{pipeline-id}/config | Get the configuration that a pipeline ran. | read | Pipeline: read | Current | |
Returns the source and compiled config for the pipeline. Needs a personal API token. Acts onpipeline Permission (capability) Pipeline: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /pipeline/{pipeline-id}/workflow | List the workflows in a pipeline. | read | Pipeline: read | Current | |
Paginated through next_page_token. Needs a personal API token. Acts onworkflow Permission (capability) Pipeline: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WorkflowsRead a workflow, list its jobs, and cancel or rerun it.4 | ||||||
| GET | /workflow/{id} | Get a workflow's summary by its ID. | read | Workflow: read | Current | |
Needs a personal API token whose user can see the project. Acts onworkflow Permission (capability) Workflow: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workflow/{id}/job | List the jobs in a workflow. | read | Workflow: read | Current | |
Paginated through next_page_token. Needs a personal API token. Acts onjob Permission (capability) Workflow: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workflow/{id}/cancel | Cancel a running workflow. | write | Workflow: write | Current | |
Stops a real run in progress. Needs a personal API token whose user can write to the project. Acts onworkflow Permission (capability) Workflow: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workflow/{id}/rerun | Rerun a workflow, either in full or from the failed jobs. | write | Workflow: write | Current | |
Starts a new run, which can deploy or change live systems. Needs a personal API token whose user can write to the project. Acts onworkflow Permission (capability) Workflow: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
JobsRead a job's details and cancel a running job.2 | ||||||
| GET | /project/{project-slug}/job/{job-number} | Get a job's details by its number within a project. | read | Job: read | Current | |
Needs a personal API token whose user can see the project. Acts onjob Permission (capability) Job: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /project/{project-slug}/job/{job-number}/cancel | Cancel a running job by its number within a project. | write | Job: write | Current | |
Stops real work in progress. Needs a personal API token whose user can write to the project. Acts onjob Permission (capability) Job: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProjectsRead a project's details, create a project, and manage its checkout keys.4 | ||||||
| GET | /project/{project-slug} | Get a project's details. | read | Project: read | Current | |
Needs a personal API token whose user can see the project. Acts onproject Permission (capability) Project: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /project | Create a new CircleCI project from a repository. | write | Project: write | Current | |
Sets a repository up for CircleCI. Needs a personal API token whose user can administer the organization. Acts onproject Permission (capability) Project: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /project/{project-slug}/checkout-key | List a project's checkout keys. | read | Project: read | Current | |
Returns key fingerprints and types, not private key material. Needs a personal API token whose user can see the project. Acts oncheckout key Permission (capability) Project: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /project/{project-slug}/checkout-key | Create a new checkout key for a project. | write | Project: write | Current | |
Adds a deploy or user key the project uses to check out source. Needs a personal API token whose user can administer the project. Acts oncheckout key Permission (capability) Project: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Contexts & secretsList, create, read, and delete contexts, and add, list, or remove the environment variables they hold.6 | ||||||
| GET | /context | List the contexts for an owner (organization). | read | Context: read | Current | |
Lists contexts by name and ID, not the values inside them. Needs a personal API token whose user can see the organization. Acts oncontext Permission (capability) Context: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /context | Create a context for an owner (organization). | write | Context: write | Current | |
A context groups shared secrets for use across projects. Needs a personal API token whose user can administer the organization. Acts oncontext Permission (capability) Context: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /context/{context_id} | Delete a context and the secrets it holds. | write | Context: write | Current | |
Removes shared secrets, which can break every build that relied on them. Needs a personal API token whose user can administer the organization. Acts oncontext Permission (capability) Context: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /context/{context_id}/environment-variable | List the environment variables in a context. | read | Context: read | Current | |
Returns variable names only, not their secret values. Needs a personal API token whose user can see the context. Acts onenvironment variable Permission (capability) Context: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /context/{context_id}/environment-variable/{env_var_name} | Add or update an environment variable in a context. | write | Context: write | Current | |
Sets a shared secret value that every project using the context can read at build time. Needs a personal API token whose user can administer the organization. Acts onenvironment variable Permission (capability) Context: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /context/{context_id}/environment-variable/{env_var_name} | Remove an environment variable from a context. | write | Context: write | Current | |
Removes a shared secret, which can break builds that read it. Needs a personal API token whose user can administer the organization. Acts onenvironment variable Permission (capability) Context: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Project environment variablesList, create, read, and delete a project's environment variables.3 | ||||||
| GET | /project/{project-slug}/environment-variable | List a project's environment variables. | read | Project: read | Current | |
Returns each variable's name and a masked value, never the full secret. Needs a personal API token whose user can see the project. Acts onenvironment variable Permission (capability) Project: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /project/{project-slug}/environment-variable | Create an environment variable on a project. | write | Project: write | Current | |
Sets a project secret that the project's builds can read. Needs a personal API token whose user can administer the project. Acts onenvironment variable Permission (capability) Project: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /project/{project-slug}/environment-variable/{name} | Delete a project's environment variable. | write | Project: write | Current | |
Removes a project secret, which can break builds that read it. Needs a personal API token whose user can administer the project. Acts onenvironment variable Permission (capability) Project: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InsightsRead aggregated metrics for an organization, a project, its workflows and jobs, and its flaky tests.3 | ||||||
| GET | /insights/{org-slug}/summary | Get aggregated metrics for an organization and its projects. | read | Insights: read | Current | |
Reveals build durations and failure rates across projects. Needs a personal API token whose user can see the organization. Acts oninsights summary Permission (capability) Insights: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /insights/{project-slug}/workflows/{workflow-name}/summary | Get metrics and trends for a project's named workflow. | read | Insights: read | Current | |
Returns duration, success rate, and throughput trends for the workflow. Needs a personal API token. Acts oninsights summary Permission (capability) Insights: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /insights/{project-slug}/flaky-tests | Get the flaky tests detected for a project. | read | Insights: read | Current | |
Surfaces tests that pass and fail inconsistently. Needs a personal API token whose user can see the project. Acts onflaky test Permission (capability) Insights: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList, create, read, update, and delete the outbound webhooks registered on a project.5 | ||||||
| GET | /webhook | List the outbound webhooks for a scope, such as a project. | read | Webhook: read | Current | |
Returns each webhook's URL and subscribed events. Needs a personal API token whose user can see the project. Acts onwebhook Permission (capability) Webhook: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /webhook | Create an outbound webhook on a project. | write | Webhook: write | Current | |
Registers a receiver URL and the events it subscribes to, such as workflow-completed and job-completed. Needs a personal API token whose user can administer the project. Acts onwebhook Permission (capability) Webhook: writeVersionAvailable since the API’s base version Webhook event workflow-completedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /webhook/{webhook-id} | Get a single outbound webhook by its ID. | read | Webhook: read | Current | |
Needs a personal API token whose user can see the project. Acts onwebhook Permission (capability) Webhook: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /webhook/{webhook-id} | Update an outbound webhook's URL or subscribed events. | write | Webhook: write | Current | |
Changes where CircleCI sends event payloads. Needs a personal API token whose user can administer the project. Acts onwebhook Permission (capability) Webhook: writeVersionAvailable since the API’s base version Webhook event job-completedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /webhook/{webhook-id} | Delete an outbound webhook. | write | Webhook: write | Current | |
Stops event deliveries to the receiver. Needs a personal API token whose user can administer the project. Acts onwebhook Permission (capability) Webhook: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UserRead the authenticated user and their collaborations.2 | ||||||
| GET | /me | Get information about the authenticated user. | read | — | Current | |
Identifies the user behind the token. Any valid personal API token can call it. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /me/collaborations | List the organizations the authenticated user collaborates in. | read | — | Current | |
Shows the organizations the token can reach. Any valid personal API token can call it. Acts oncollaboration Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CircleCI can notify an app or AI agent when a run finishes, instead of the app repeatedly asking. It posts the event payload to a webhook URL registered on a project, and a signature header lets the receiver confirm the payload came from CircleCI.
| Event | What it signals | Triggered by |
|---|---|---|
workflow-completed | Fires when a workflow reaches a terminal state, meaning every job in it has finished. The payload includes the workflow's name, status, and timings, plus its project, organization, pipeline, and the commit that started the run. | In-app only |
job-completed | Fires when a single job finishes, after all its steps have run. The payload includes the job's name, status, and timings, plus its parent workflow and pipeline, the project and organization, and the associated commit. | In-app only |
CircleCI limits how fast an app or AI agent can call, and reports the state of that limit in response headers. The published limits are deliberately loose, and CircleCI reserves the right to throttle heavy or bursty traffic.
CircleCI does not publish a fixed numeric limit. The developer guide states that it reserves the right to throttle requests from an individual user or against individual resources, to guard against sudden bursts and sustained high volume. When a call is throttled it returns 429, and the response carries headers that report the current state: a RateLimit-Limit (or X-RateLimit-Limit-
List endpoints use token-based pagination. A response that has more results includes a next_page_token field, and the next page is fetched by sending that value back as the page-token query parameter. When next_page_token is null, there are no more pages.
Requests and responses are JSON. CircleCI does not document a single payload size cap across the API; individual endpoints set their own page sizes through the page-token cursor rather than a caller-set page-size parameter.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed, such as an unexpected or invalid request body. | Correct the request body or parameters and resend. |
| 401 | Unauthorized | The credentials provided are missing or invalid. The Circle-Token is absent, wrong, or has been revoked. | Send a valid personal API token in the Circle-Token header. |
| 403 | Forbidden | The token is valid but the user it belongs to is not permitted to act on this resource. | Use a token whose user has access to the project or organization. |
| 404 | Not Found | The entity was not found. The resource does not exist, or the token's user cannot see it. | Confirm the path, the project slug, and that the user has access. |
| 429 | Too Many Requests | An API rate limit was exceeded and the request was throttled. | Wait the number of seconds in the Retry-After header, then retry with backoff. |
| 500 | Internal Server Error | An unexpected error occurred on CircleCI's side. | Retry after a short delay, and contact CircleCI support if it persists. |
CircleCI runs a single, continuously updated v2 REST API rather than dated versions. The version sits in the path, and CircleCI ships changes through dated release notes.
The v2 REST API is the current API, with the version named in the path. It is continuously updated rather than dated, so an integration calls v2 directly with no version header to pin. CircleCI announces changes, including upcoming breaking changes, through dated release notes.
CircleCI shipped a way to preview the impact of three config-compilation breaking changes scheduled for 17 August 2026. The changes affect undeclared parameters, regex engine evaluation, and the requirement for version 2.0 support. Users can run a validation with the next ruleset, through the CLI or the config editor, to see the impact ahead of the cutover.
CircleCI published its first-party MCP server, the open-source @circleci/mcp-server-circleci, so AI assistants can query builds in natural language, such as finding the latest failed pipeline on a branch and pulling its logs. It uses the same personal API token as the REST API.
An integration calls the v2 API directly; there is no version header to pin.
CircleCI changelog ↗Bollard AI sits between a team's AI agents and CircleCI. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.