CircleCI REST API

Name: CircleCI REST API API
Brand: CircleCI REST API
Availability: InStock

★ 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.

Quickstart

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.

Capabilities

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

Start building with CircleCI REST API API

Explore with Jentic

View OpenAPI Document

Use Cases

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

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

Why though Jentic?

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.

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.

Alternative

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.

Complementary

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.

FAQs

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.