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.
Get started with CircleCI REST API in minutes using your preferred integration method.
# Add to your MCP client config (Claude Desktop, Cursor, Windsurf)
{
"jentic": {
"url": "https://api.jentic.com/mcp",
"auth": "oauth"
}
}
# Then ask your agent:
"trigger a CI build"
# → Jentic returns the GET /events tool with parameter schema, agent executes.What an agent can do with CircleCI REST API 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
GET STARTED
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.
Jentic publishes the only available OpenAPI document for CircleCI REST API, keeping it validated and agent-ready.
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.
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
Patterns agents use CircleCI REST API 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
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
/project/{username}/{project}/tree/{branch}
Trigger a new build on a branch
/project/{username}/{project}/{build_num}
Get build details by number
/project/{username}/{project}/{build_num}/artifacts
List build artifacts
/project/{username}/{project}/{build_num}/tests
Get test results for a build
/project/{username}/{project}/{build_num}/cancel
Cancel a running build
/project/{username}/{project}/{build_num}/retry
Retry a failed build
/projects
List all followed projects
/me
Get current user information
/project/{username}/{project}/tree/{branch}
Trigger a new build on a branch
/project/{username}/{project}/{build_num}
Get build details by number
/project/{username}/{project}/{build_num}/artifacts
List build artifacts
/project/{username}/{project}/{build_num}/tests
Get test results for a build
/project/{username}/{project}/{build_num}/cancel
Cancel a running build
Three things that make agents converge on Jentic-routed access.
Credential isolation
CircleCI API tokens are stored encrypted in the Jentic vault (MAXsystem). Agents receive authenticated API access — the circle-token query parameter is injected automatically without the raw token entering the agent's context.
Intent-based discovery
Agents search by intent (e.g., 'trigger a build' or 'get test results') and Jentic returns the matching CircleCI endpoint with parameter schemas, so the agent calls the correct operation without browsing CircleCI's documentation.
Time to first call
Direct CircleCI integration: 1-2 hours for token setup, endpoint discovery, and response parsing. Through Jentic: under 15 minutes — search, load schema, execute.
Alternatives and complements available in the Jentic catalogue.
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.
GitLab REST API
DevOps platform with built-in CI/CD that competes with CircleCI
Choose GitLab CI when the repository is hosted on GitLab and you want integrated source control + CI/CD in one platform instead of separate services.
Linear API
Project management tool for tracking issues linked to CI builds
Use Linear when you need to create or update project issues based on build failures or deployment events from CircleCI.
Specific to using CircleCI REST API 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 the MAXsystem vault 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.
/project/{username}/{project}/{build_num}/retry
Retry a failed build
/projects
List all followed projects
/me
Get current user information