CircleCI Pipelines & Workflows
When a build goes red, pull the project's latest pipelines, open the failing workflow and see which job broke, then rerun just the failed jobs or cancel a stuck workflow. Can also start a new CircleCI pipeline run on a branch or tag.
Connect this API to an AI agent Browse all specs
What you can do with CircleCI Pipelines & Workflows via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /me |
getCurrentUser | Check which CircleCI user the token belongs to |
| GET | /project/{project-slug}/pipeline |
listProjectPipelines | List a project's recent pipelines, optionally for one branch |
| GET | /project/{project-slug}/pipeline/{pipeline-number} |
getPipelineByNumber | Get a pipeline by its number in the project |
| GET | /pipeline/{pipeline-id} |
getPipeline | Get a pipeline by id: trigger, branch, commit and state |
| GET | /pipeline/{pipeline-id}/workflow |
listPipelineWorkflows | List the workflows of a pipeline and their status |
| GET | /workflow/{id} |
getWorkflow | Get a workflow's status, timing and who started it |
| GET | /workflow/{id}/job |
listWorkflowJobs | List the jobs in a workflow with status and job number |
| GET | /jobs/{job_id} |
getJob | Get a job's name, number, type and status by job id |
| POST | /project/{provider}/{organization}/{project}/pipeline/run |
triggerPipelineRun | Start a new pipeline run on a branch or tag |
| POST | /workflow/{id}/rerun |
rerunWorkflow | Rerun a workflow, optionally only its failed jobs |
| POST | /workflow/{id}/cancel |
cancelWorkflow | Cancel a running workflow |
Authentication
api_key_header
API key — sent as the Circle-Token header
CircleCI personal API token, sent in the Circle-Token header. Project API tokens do not work with API v2.
How to get a credential
- Sign in to CircleCI and open User Settings > Personal API Tokens (https://app.circleci.com/settings/user/tokens).
- Click Create New Token and give it a name such as
vx-agent. - Copy the token right away; it is shown only once.
- The token acts as you: it can see and run every project you can, so use a CircleCI user with only the projects the agent needs.
Permissions used
| Access (from your CircleCI user role) | Operations |
|---|---|
| Read (any project member) | getCurrentUser, listProjectPipelines, getPipelineByNumber, getPipeline, listPipelineWorkflows, getWorkflow, listWorkflowJobs, getJob |
| Write (contributor or admin on the project) | triggerPipelineRun, rerunWorkflow, cancelWorkflow |
Common errors
| Status | Meaning | Fix |
|---|---|---|
| 401 | Token missing, revoked or a project token | Create a personal API token and update the credential |
| 403 | Your user cannot run or change this project | Ask an org admin for contributor access |
| 404 | Wrong project slug or the token cannot see the project | Use the slug from Project Settings > Overview (e.g. gh/acme/web) |
| 400 | Bad body (branch and tag together, unknown definition id) | Send either branch or tag; check the pipeline definition |
| 429 | Rate limited | Wait for Retry-After seconds and retry |
Store the token as a VX Agents credential (API key) so it is never pasted into chats or prompts.
Usage guide
Setup
- Credential: a CircleCI personal API token (User Settings > Personal API Tokens), stored as a VX Agents API key credential. Project tokens do not work with API v2.
- Pin the project slug you work on, shown in Project Settings > Overview:
gh/<org>/<repo>,bb/<org>/<repo>, or for GitHub App / GitLab orgs an opaquecircleci/<org-id>/<project-id>. - For triggerPipelineRun also pin
provider,organization,project(the three parts of the slug) and the pipelinedefinition_id(Project Settings > Pipelines). - Call
getCurrentUseronce to confirm the token works.
Find out why a build failed
listProjectPipelineswith the slug (optionallybranch=main) → newest pipelines first; noteidandnumber.listPipelineWorkflowswith the pipeline id → find the workflow with statusfailedorerror.listWorkflowJobswith the workflow id → jobs with statusfailed; notejob_numberandid.getJobwith the job id for its type, timing and status; send the user to the job page in the CircleCI app for the full step log.- Fix forward or retry:
rerunWorkflowwith{"from_failed": true}reruns only the failed jobs;cancelWorkflowstops a stuck run.
Start a pipeline
triggerPipelineRun with definition_id, config.branch (where to read .circleci/config.yml), checkout.branch (code to build) and optional parameters. Use either branch or tag, not both.
Good to know
- Triggering, rerunning and cancelling use build credits or stop someone's work: show the project, branch and workflow to the user and get confirmation first.
- Lists page with
next_page_token; pass it back aspage-token. - Pipeline ids, workflow ids and job ids are UUIDs; pipeline and job numbers are per-project integers.
- Workflow status values: success, running, not_run, failed, error, failing, on_hold, canceled, unauthorized.
- The older
POST /project/{project-slug}/pipelineis superseded in the docs, so this spec uses the recommended Trigger Pipeline API (not available for GitLab projects). - This spec has no artifacts or test-results endpoints.
Source: CircleCI API v2 reference (https://circleci.com/docs/api/v2/index.html), checked 2026-10-16.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “CircleCI Pipelines & Workflows” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.