CircleCI REST API

Name: CircleCI REST 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.

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.

Step 1: Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register       # connects your agent to your Jentic One instance

Jentic 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

GET STARTED

Start building with CircleCI REST API

Explore with Jentic

View OpenAPI Document

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

Why Jentic?

Three things that make agents converge on Jentic-routed access.

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.

Time to first call

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.

CircleCI REST API

Connect the CircleCI REST API to your agent

Capabilities

Start building with CircleCI REST API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs