CircleCI API for CI/CD Agents

Triggering a pipeline is one of the safest writes an agent can make. Worst case you burn some build minutes and someone gets a red check on a branch nobody cares about.

Cancelling one is a different story, and the API shape is the reason. POST /workflow/{id}/cancel takes a workflow ID and nothing else. No project in the path, no organisation, nothing that scopes it to work your agent started.

So if your agent can name a workflow ID, and your token can reach that project, it can cancel it. Including the release deploy a colleague kicked off four minutes ago.

Same for rerun, with a twist

POST /workflow/{id}/rerun has the same unscoped shape, and it accepts from_failed, a jobs list, and enable_ssh.

That last flag deserves attention. Rerunning with SSH enabled opens an interactive session into the build environment, which is a lovely debugging tool for a human and an odd capability to hand a language model. If your agent has rerun access, pin enable_ssh to false in policy rather than trusting that it will never be set.

A rerun is also not free in the way a human reading a dashboard might assume. Reruns consume credits, and an agent that reruns every failed workflow to "check if it was flaky" is an expensive way to discover that your tests are, in fact, flaky.

Auth and the two slug formats

API v2 lives at https://circleci.com/api/v2 and the usual auth is a Circle-Token header. The spec also lists bearer and basic auth, plus an API key query parameter, which you should avoid for the obvious reason that query strings end up in logs.

The project slug is where people lose time. It is normally three parts:

• vcs-slug/org-name/repo-name, for example gh/CircleCI-Public/api-preview-docs.
• But for GitLab projects and GitHub App projects, the VCS slug is the literal string circleci, and the other two parts become the organisation ID and the project ID rather than readable names.

A model that has seen a hundred blog posts using the first format will construct it from your org and repo name and get a confusing 404 on a project that plainly exists. Resolve the slug once, store it in config, and never let it be assembled from guesses. If you are on GitLab, the second format is almost certainly yours.

Also note that the recommended trigger endpoint has moved. POST /project/{provider}/{organization}/{project}/pipeline/run takes a pipeline definition ID and is the current path; the older POST /project/{project-slug}/pipeline is marked superseded. Pin the one you mean, because this is exactly the drift described in API versioning strategy when AI agents are your consumers: a human reads the deprecation note, an agent keeps calling the old path until it stops working.

Setting it up

npx swytchcode
swy login
swy init --mode=sandbox

swy get circleci
swy auth connect circleci         # token stored outside the project
swy auth status

swy discover "get workflow jobs" --project circleci
swy discover "trigger a pipeline" --project circleci
swy list methods circleci

swy info <canonical_id>
swy add method <canonical_id>     # reads + trigger. Cancel and rerun: see below.

The split we would ship:

• Allow freely: read pipelines, workflows, jobs, test metadata, artifacts, insights. This is where nearly all the value of a CI agent lives and none of the risk.
• Allow with care: trigger a pipeline, scoped by policy to specific projects and branches.
• Leave out: cancel, rerun with SSH, and anything touching project settings, contexts or environment variables. A token that can read your CI config is one thing; an agent that can edit an environment variable in a deploy context is a supply-chain problem.

The token lives in a local store outside your project, encrypted at rest, and is injected at call time so it never enters the model's context. See the authentication docs. Keep --project circleci on discover, and run swy get before swy info.

The policy that keeps an agent in its lane

Because cancel and rerun are unscoped by design, policy is where you put the scope back.

{
  "id": "no-ssh-reruns",
  "target": ["<circleci rerun-workflow canonical_id>"],
  "when": { "field": "enable_ssh", "operator": "==", "value": true },
  "action": {
    "type": "DENY",
    "message": "Reruns with SSH access are not available to agents"
  }
}

Then add a trigger rule restricting which branches an agent may build, so it cannot kick off a pipeline against main. A deny is right for the SSH case because there is no situation where you want to be asked; an approval gate is right for triggering a deploy pipeline, where the answer is sometimes yes.

Check the available operators in the policy reference, and keep the rules in version control so changing what your CI agent may touch is a reviewed diff. In a CI context that review trail is the point: see policy-as-code for AI agents.

Idempotency: the pipeline storm

Triggering is not idempotent. The request lands, CircleCI starts a pipeline, the response is lost, your agent retries, and now two identical pipelines are running against the same commit, competing for runners and both burning credits.

Writes are only auto-retried when an idempotency key is set, so an unprotected trigger fails visibly rather than doubling your queue. Derive the key from the commit SHA plus the pipeline purpose, which is naturally stable, so a retry collapses onto the original. Then before triggering, list recent pipelines for that SHA and skip if one is already running. Background in API idempotency: the complete guide, mechanics in the retries guide.

On rate limits, CircleCI does not publish numbers but returns 429 with "API rate limits exceeded" on many endpoints. Backoff is automatic; the design fix is to stop polling. An agent checking build status every two seconds across forty pipelines is the usual culprit, and API observability for AI agents covers how to see that pattern in your own traffic.

From Claude Code, where this actually belongs

CI is the best MCP use case in this whole series, because you are already in your editor when a build fails. Connect through the MCP server and you can ask why the pipeline failed, get the relevant job output and test metadata, and fix it without leaving the terminal. With reads allowlisted and writes gated, that session cannot cancel anything. Setup is in the MCP setup guide, the reference in the MCP docs, and skills.md gives a coding agent the conventions.

What you can build

1. A failure triage agent. On a red build, pull the failing job's output and test metadata, classify it as a real failure, a flake, or an infrastructure problem, and post the verdict with the relevant log lines. Read-only, and it saves the five minutes everyone spends scrolling build output.
2. A flake detector. Read test metadata across runs and find the tests that fail intermittently on unchanged code. This is a genuinely hard thing for humans to notice and trivial for a job that reads every run.
3. Build-time and credit reporting. Track which jobs are getting slower and which are eating the credit budget, then report weekly. Pure reads, and it funds itself the first time it finds a cache misconfiguration.
4. A PR-to-CI loop. When a pull request opens, trigger the right pipeline and post results back as a comment. Pairs with connecting GitHub to an AI agent and the hands-on GitHub AI agent walkthrough.

FAQ

Should an agent be able to cancel workflows?

Rarely, and not without a policy that checks the project and branch first, because the endpoint itself provides no scoping. The legitimate case is cancelling superseded runs on a branch the agent itself triggered, which you can express as a rule rather than as general cancel access.

My project slug 404s and the project exists. Why?

You are probably using gh/org/repo for a GitLab or GitHub App project, which needs circleci as the VCS slug plus the organisation and project IDs instead of names.

What about GitLab CI instead?

Same agent design, different token model, and the token question there is sharper. The GitLab guide covers project-scoped versus group tokens, which is the decision that determines how much an agent can reach.

How do I prove what the agent did to our pipelines?

swy audit network lists every call with its arguments, so "who cancelled the deploy" has an answer, and swy audit policy lists what a rule stopped. See how to log every API call an AI agent makes.

Related reading

• CircleCI integration page
• GitLab AI API and CI Agents
• How to Connect GitHub to an AI Agent
• Can AI Do API Testing? What Works and What Doesn't
• Browse all 300+ API integrations