canonical: https://jentic.com/apis/circleci.com/circleci

# CircleCI REST API

Trigger builds, inspect project pipelines, manage environment variables, and retrieve test results and build artifacts through CircleCI's REST API. Supports API token authentication passed as a query parameter for all 22 endpoints. Covers the core CI/CD loop from triggering branch-specific builds through artifact retrieval and SSH key management for deployment.

## For AI agents

Trigger CI/CD builds, check pipeline status, retrieve test results and artifacts, and manage project environment variables on CircleCI. Covers 22 endpoints for build automation.

## Scope

Does not handle source control, container orchestration, or deployment infrastructure - use for CI/CD build triggering, status monitoring, and artifact retrieval only.

## Capabilities

- Trigger builds on specific branches with custom parameters and environment variable overrides
- Retrieve detailed build status including step-level timing and failure information
- Download build artifacts by path for deployment pipelines and release workflows
- Inspect test result metadata including failure messages and timing for flaky test detection
- Configure project-level environment variables and SSH keys for secure deployments
- Cancel running builds and retry failed builds with optional SSH debug access
- List all followed projects with their most recent build status and default branch

## Use cases

### AI Agent Build Monitoring and Triage

AI agents use the CircleCI API through Jentic to monitor build pipelines, detect failures, and triage issues automatically. An agent searches Jentic for 'check build status', receives the schema for GET /project/{username}/{project}/{build_num}, and reads step-level output to identify which stage failed. Agents can then retry transient failures or create tickets for real issues without human intervention.

Example prompt: Get the latest build for acme/backend on the main branch, check if it failed, retrieve the test results to identify failing tests, and retry if the failure was in a network-dependent step

### Branch Build Triggering for Deploy Pipelines

Trigger builds on specific branches as part of automated deployment workflows. The API accepts branch parameters and returns build numbers for status tracking. Teams integrate this into ChatOps flows where a deploy command triggers a build, monitors progress, and reports back when deployment completes or fails.

Example prompt: Trigger a new build for acme/frontend on the release/v2.0 branch, poll the build status every 30 seconds until completion, then report the outcome

### Test Result Analysis and Flaky Test Detection

Retrieve test metadata from builds to analyze failure patterns, identify flaky tests, and calculate test suite reliability metrics. The API returns test names, classnames, duration, and result status. Agents can aggregate results across multiple builds to detect intermittently failing tests that waste developer time.

Example prompt: Retrieve test results for the last 10 builds of acme/backend on main, identify any tests that failed in more than 2 of those builds, and report them as potentially flaky

### Build Artifact Retrieval for Release Management

Download compiled artifacts, coverage reports, and deployment packages from successful builds. The API lists all artifacts by path with download URLs. Release automation pipelines use this to fetch the production build output after CI passes and deploy it to staging or production environments.

Example prompt: List all artifacts from the latest successful build of acme/cli on the main branch, find the binary matching linux-amd64, and return its download URL

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /project/{username}/{project}/tree/{branch} | Trigger a new build on a branch |
| GET | /project/{username}/{project}/{build_num} | Get build details by number |
| GET | /project/{username}/{project}/{build_num}/artifacts | List build artifacts |
| GET | /project/{username}/{project}/{build_num}/tests | Get test results for a build |
| POST | /project/{username}/{project}/{build_num}/cancel | Cancel a running build |
| POST | /project/{username}/{project}/{build_num}/retry | Retry a failed build |
| GET | /projects | List all followed projects |
| GET | /me | Get current user information |

## Key resources

- **Projects** — List followed projects, view settings, and manage project configuration
- **Builds** — Trigger, cancel, retry builds and inspect step-level execution details
- **Artifacts** — List and download build output files and compiled assets
- **Tests** — Retrieve test result metadata including pass/fail status and timing
- **Environment Variables** — Set and manage project-level environment variables for builds
- **Checkout Keys** — Manage SSH checkout keys for repository access during builds

## Why Jentic

- **Setup:** Wiring the CircleCI REST API by hand means managing its API token and threading build triggering, status polling, and artifact retrieval through project-scoped endpoints yourself. Through Jentic you install once, import the CircleCI REST API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** CircleCI puts the username and project in the URL path (/project/{username}/{project}/...), so a rule can pin your agent to one project: it can trigger builds and read status there and nowhere else. You choose the operations it may call, so canceling or retrying builds is not included unless you add it.
- **Credential handling:** Your CircleCI token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'trigger a build on a branch' or 'get build artifacts', and Jentic returns the matching CircleCI operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **GitHub v3 REST API** — Source control platform whose repositories CircleCI builds and tests
- **GitLab REST API** — DevOps platform with built-in CI/CD that competes with CircleCI
- **Linear API** — Project management tool for tracking issues linked to CI builds

## FAQ

### What authentication does the CircleCI REST API use?

The CircleCI API v1 uses an API token passed as a query parameter named circle-token. You generate personal API tokens from your CircleCI account settings. Through Jentic, the token is stored encrypted in your Jentic One instance and appended to requests automatically - agents never see the raw token value. Project-level tokens offer more restricted access for CI-only automation.

### How do I trigger a build through the CircleCI API via Jentic?

Search Jentic for 'trigger a circleci build', load the operation schema for POST /project/{username}/{project}/tree/{branch}, and execute with the target branch name. Jentic handles token injection via the circle-token query parameter. You can optionally pass build_parameters to set environment variables for that specific build. The response returns the build number for status tracking.

### What are the rate limits for the CircleCI REST API?

CircleCI applies rate limiting on API requests but does not publish exact per-endpoint limits. The API returns HTTP 429 when limits are exceeded. For typical automation use cases (build triggers, status checks), the limits are generous enough that throttling rarely occurs. Polling for build status every 10-30 seconds is well within limits.

### Can I retrieve test results from a CircleCI build?

Yes. Use GET /project/{username}/{project}/{build_num}/tests to retrieve test metadata for a completed build. The response includes test name, classname, file path, result (success/failure), run_time, and failure message. This requires that your build configuration stores test results in JUnit XML format using the store_test_results step.

### How do I download build artifacts from CircleCI?

Use GET /project/{username}/{project}/{build_num}/artifacts to list all artifacts for a build. Each artifact entry includes the path, node_index, and a URL for downloading. Append your circle-token to the download URL as a query parameter. Through Jentic, authentication is handled automatically when accessing artifact URLs.

### Is the CircleCI REST API free to use?

API access is included with all CircleCI plans including the Free tier. The Free plan provides 6000 build minutes per month for Linux and limited credits for other platforms. API calls themselves have no separate cost. Usage charges are based on compute minutes consumed by builds, not API request volume.

### Can I limit what my agent is allowed to do with the CircleCI REST API?

Yes. Because CircleCI puts the username and project in the URL path, such as /project/{username}/{project}/tree/{branch}, a rule in your self-hosted Jentic One can pin the agent to a single project so it triggers builds and reads build status there and nowhere else. You decide which operations are allowed, so canceling a running build or retrying a failed one is excluded unless you explicitly add those operations. The CircleCI token stays stored by your own Jentic One instance and is injected only on calls the agent is permitted to make.