CircleCI REST API
★ Only Publicly Available OpenAPI DocumentDeveloper ToolsCi CdapiKey22 EndpointsREST
For 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.
Use for: I need to trigger a build on a specific branch, I want to check the status of the latest build for a project, Retrieve the test results from a failed build, List all build artifacts for a specific build number
Not supported: Does not handle source control, container orchestration, or deployment infrastructure - use for CI/CD build triggering, status monitoring, and artifact retrieval only.
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.
Install Jentic One Beta
Connect the CircleCI REST API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the CircleCI REST API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcircleci.com%2Fcircleci" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcircleci.com%2Fcircleci" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with CircleCI REST API.
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
Patterns agents use CircleCI REST API for, with concrete tasks.
★ 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.
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.
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.
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.
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
22 endpoints — trigger builds, inspect project pipelines, manage environment variables, and retrieve test results and build artifacts through circleci's rest api.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
Complementary
GitHub v3 REST API
Source control platform whose repositories CircleCI builds and tests
Use GitHub API when you need to manage the source repository (PRs, branches, issues) that CircleCI builds from. Combine for full code-to-deploy automation.
FAQs
Specific to using CircleCI REST API through Jentic.
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.
GET STARTED