# CircleCI API V3

CircleCI's V3 API. Every route is served under `/api/v3` on `https://circleci.com`.

No standard is implemented. V3 takes the ideas that work from established API designs and combines them into one coherent whole, but it is not JSON:API, not `problem+json`, and not HAL. Familiar names like `data`, `attributes`, `source.pointer` and `filter[...]` carry no behaviour from those specs. Take everything from this document, and do not use a standard-conformant client library.

Every endpoint is listed below, with the full detail for each entity's operations
in its own file. Every file is listed in https://circleci.com/docs/api/v3/llms.txt, and the conventions that follow are
also served alone at https://circleci.com/docs/api/v3/conventions.md.

The machine-readable description of this API is https://circleci.com/fullopenapi.yaml
(JSON at https://circleci.com/fullopenapi.json), catalogued at
https://circleci.com/.well-known/api-catalog.

## Conventions

### Auth

`Authorization: Bearer <token>`. A token in a query parameter is rejected.

### Ids

Ids are UUIDs, never slugs or names. Some collections resolve a slug via `filter[slug]`.

### One resource

`{"data": {"id", "attributes", "references"}}`. Each entry in `references` is an `id`, or an array of them, sometimes carrying a nested `attributes` object of denormalised fields from the referenced resource. Read the operation's schema for which fields those are, and fetch the resource itself for anything not listed - there is no way to request more inline.

### A collection

`{"data": [...], "page": {"next", "prev"}}`. `page.next` and `page.prev` are opaque cursor values, not URLs - send one back as `page[cursor]`, unmodified, and stop when `page.next` is `null`. `page[limit]` bounds are per-operation, and out of range is a 400, not a clamp.

### Scoping

Scoping uses `filter[...]`. Most list operations require a scope filter such as `filter[org_id]` or `filter[project_id]` and return 400 without it, so read the operation's parameters.

### Methods

`GET` reads, `POST` creates and performs named actions and partial updates, `PUT` replaces in full, `DELETE` removes. There is no `PATCH`.

### Retrying

`GET`, `PUT` and `DELETE` are idempotent. V3 aims for idempotent `POST` wherever an operation allows it, but never assume a given `POST` is replayable: retrying one that timed out can create a second resource or fire an action twice. Retry a `POST` only if its own description says it is idempotent - otherwise re-read the collection to find out whether the first attempt landed.

### Destructive operations

`DELETE`, and `POST` actions such as `cancel`, `delete`, `revoke` and `purge`, take effect immediately and normally cannot be undone. Treat them as irreversible: no operation here reverses another, and there is no dry-run mode. Where recovery is possible at all it is a support matter, not an API call.

### Errors

Errors return a single `error` object, never an `errors` array: `{"error": {"type", "id", "title", "detail", "source"}}`. Branch on the status code; every member is optional. `error.type`, where present, separates causes within one status and is a bare token, not a URI. Never branch on `title` or `detail`. Quote `error.id` in support requests. Invalid input is always 400, never 422.

### Rate limits

On 429, wait the `Retry-After` seconds, then back off exponentially. Responses carry `RateLimit-Policy` and `RateLimit`, the policy and the current state against it (IETF draft-ietf-httpapi-ratelimit-headers). Limits are per route and are not published: read the headers rather than assuming a figure.

### Caching

Responses carry an `ETag` and a `Cache-Control` directive. Where a response has an `ETag`, send it back as `If-None-Match` to make the request conditional and get a 304 when nothing has changed.

### Deprecation

A deprecated operation is marked `deprecated: true` and its responses carry `Deprecation`, whose value is `true` (RFC 9745), `Sunset`, the HTTP-date when the endpoint will be removed (RFC 8594), and `Link` with `rel="deprecation"`, pointing at the migration documentation (RFC 8288). Migrate before the `Sunset` date. A removed route returns 410, permanently.

### Additions

Response fields are added without a version change. Ignore members you do not recognise rather than failing to parse.

## Endpoints

### Analysis Charges

Credit spend aggregated by job, workflow or pipeline.

Full detail: https://circleci.com/docs/api/v3/analysis-charges.md

- `POST /api/v3/analysis/charges` - Returns entities ranked by what they were charged.

### Analysis Jobs

Aggregated job analytics across time.

Full detail: https://circleci.com/docs/api/v3/analysis-jobs.md

- `POST /api/v3/analysis/jobs` - Returns aggregated job results across runs.

### Analysis Tests

Aggregated test analytics across time.

Full detail: https://circleci.com/docs/api/v3/analysis-tests.md

- `POST /api/v3/analysis/tests` - Returns aggregated test results across runs.

### Analysis Usage

Resource consumption aggregated by job, workflow or pipeline.

Full detail: https://circleci.com/docs/api/v3/analysis-usage.md

- `POST /api/v3/analysis/usage` - Returns entities ranked by the resources they consumed.

### Catalog

Marketplace catalog of available products and add-ons.

Full detail: https://circleci.com/docs/api/v3/catalog.md

- `GET /api/v3/catalog/offerings`

### Configs

Configuration compilation and validation.

Full detail: https://circleci.com/docs/api/v3/configs.md

- `POST /api/v3/configs/compile` - Compiles the supplied pipeline config, expanding orbs and resolving parameters.

### Context Restrictions

Restrictions that limit which projects, groups, or expressions may use a context.

Full detail: https://circleci.com/docs/api/v3/context-restrictions.md

- `GET /api/v3/context-restrictions` - Lists the restrictions applied to a context.
- `POST /api/v3/context-restrictions` - Creates a restriction for the context referenced in the request body.
- `DELETE /api/v3/context-restrictions/:id` - Deletes a context restriction by id, scoped to the required context_id filter.

### Contexts

Secret contexts that provide environment variables to jobs at runtime.

Full detail: https://circleci.com/docs/api/v3/contexts.md

- `GET /api/v3/contexts` - Lists the contexts owned by an organization.
- `POST /api/v3/contexts` - Creates a context owned by an organization.
- `GET /api/v3/contexts/:id` - Returns a single context by id.
- `DELETE /api/v3/contexts/:id` - Deletes a context by id.
- `GET /api/v3/contexts/:id/env-vars` - Lists the environment variables of a context.
- `DELETE /api/v3/contexts/:id/env-vars` - Deletes an environment variable from a context by name.
- `POST /api/v3/contexts/:id/env-vars/set` - Creates or updates an environment variable in a context.

### Deploy Components

Release tracker components representing deployable units.

Full detail: https://circleci.com/docs/api/v3/deploy-components.md

- `GET /api/v3/deploy/components` - Returns an organization's deploy components, ordered by name.
- `GET /api/v3/deploy/components/:id` - Returns a single deploy component by id.
- `GET /api/v3/deploy/components/:id/versions` - Returns a component's versions, most recently deployed first.

### Deploy Config Suggestions

Async requests to validate a CircleCI config and generate a suggested deploy config.

Full detail: https://circleci.com/docs/api/v3/deploy-config-suggestions.md

- `POST /api/v3/deploy/config-suggestions` - Validates a CircleCI config and asynchronously
- `GET /api/v3/deploy/config-suggestions/:id` - Returns the status of an async config suggestion request.

### Deploy Deployments

A deployment is one attempt to move a deploy component to a target version in an environment. Read in the scope of an organization via filter[org_id].

Full detail: https://circleci.com/docs/api/v3/deploy-deployments.md

- `GET /api/v3/deploy/deployments` - Returns an organization's deployments, most recently created first.

### Deploy Diff Summaries

Async requests to generate a human-readable summary of a code diff.

Full detail: https://circleci.com/docs/api/v3/deploy-diff-summaries.md

- `POST /api/v3/deploy/diff-summaries` - Generates a summary of a diff asynchronously.
- `GET /api/v3/deploy/diff-summaries/:id` - Gets the status of an async diff summary request.

### Deploy Environments

Release tracker environments for deployment management.

Full detail: https://circleci.com/docs/api/v3/deploy-environments.md

- `GET /api/v3/deploy/environments` - Returns an organization's deploy environments, ordered by name.
- `GET /api/v3/deploy/environments/:id` - Returns a single deploy environment by id.

### Deploy Settings

Per-project deploy configuration — the pipeline definitions run to deploy and to roll back. A singleton per project rather than an independently addressable resource.

Full detail: https://circleci.com/docs/api/v3/deploy-settings.md

- `GET /api/v3/deploy/settings` - Returns a project's deploy settings.

### Jobs

Individual units of work within a workflow. Each job runs in its own execution environment and produces artifacts, test results, and logs.

Full detail: https://circleci.com/docs/api/v3/jobs.md

- `GET /api/v3/jobs` - Lists the jobs in a workflow.
- `GET /api/v3/jobs/:id` - Fetches a single job, including its steps and parallel executions.
- `GET /api/v3/jobs/:id/artifacts` - Lists the artifacts produced by a job's parallel executions.
- `GET /api/v3/jobs/:id/resource-usage` - Returns a job's recorded resource usage per parallel execution.
- `GET /api/v3/jobs/:id/stderr` - Returns the stderr of a job step for a given parallel execution.
- `GET /api/v3/jobs/:id/stdout` - Returns the stdout of a job step for a given parallel execution.
- `GET /api/v3/jobs/:id/tests` - Returns a job's structured test results as JSON Lines.
- `GET /api/v3/jobs/:id/stdout/condensed` - Returns a step's stdout condensed to its most error-relevant lines, suitable for AI-agent consumption.

### Metric Counts

Time-bucketed count metrics (test result counts and test flake counts) over a time window.

Full detail: https://circleci.com/docs/api/v3/metric-counts.md

- `POST /api/v3/metric/counts` - Returns time-bucketed counts for a named metric.

### Metric Distributions

Time-bucketed distribution metrics (e.g. test result duration percentiles) over a time window.

Full detail: https://circleci.com/docs/api/v3/metric-distributions.md

- `POST /api/v3/metric/distributions` - Returns time-bucketed distribution metrics for a named metric.

### Namespaces

Scoping containers that group orbs under an organization. An orb's full name is namespace/orb-name.

Full detail: https://circleci.com/docs/api/v3/namespaces.md

- `GET /api/v3/namespaces` - List namespaces.
- `POST /api/v3/namespaces` - Create a new namespace.
- `GET /api/v3/namespaces/:id` - Retrieve a single namespace by its ID.
- `DELETE /api/v3/namespaces/:id` - Delete a namespace.
- `POST /api/v3/namespaces/import` - Import a namespace.
- `POST /api/v3/namespaces/:id/rename` - Rename a namespace.

### Notification Channel Configs

Per-user and per-project notification channel configuration — the email address or Slack channel a notification is delivered to.

Full detail: https://circleci.com/docs/api/v3/notification-channel-configs.md

- `GET /api/v3/notification/channel-configs` - Serves the V3 channel-config collection.
- `POST /api/v3/notification/channel-configs` - Creates (or replaces) a channel config.
- `GET /api/v3/notification/channel-configs/:id` - Returns a single channel config addressed by its row id.
- `DELETE /api/v3/notification/channel-configs/:id` - Deletes the channel config addressed by id.
- `POST /api/v3/notification/channel-configs/:id/update` - Applies a partial update to the channel config.

### Notification Integrations

Currently Slack workspace integrations for an organization. Manage the connection used to deliver CircleCI notifications.

Full detail: https://circleci.com/docs/api/v3/notification-integrations.md

- `GET /api/v3/notification/integrations` - List notification integrations.
- `GET /api/v3/notification/integrations/:id` - Retrieve a single notification integration by its ID.
- `DELETE /api/v3/notification/integrations/:id` - Delete a notification integration.
- `POST /api/v3/notification/integrations/:id/set-status` - Set status.

### Notification Links

Links between a CircleCI user and an external identity on a third-party connection (e.g. a Slack user). Used to deliver notifications, enable interactivity, and tag authors on that identity. Keyed by user, connection type, and external scope; not UUID-addressable.

Full detail: https://circleci.com/docs/api/v3/notification-links.md

- `GET /api/v3/notification/links` - Lists the authenticated caller's external identity links.
- `DELETE /api/v3/notification/links` - Removes a single external identity link.

### Notification Preferences

Per-user and per-project notification preference matrix. Read the matrix or bulk-toggle entries; scoped via filter[scope]=user|project.

Full detail: https://circleci.com/docs/api/v3/notification-preferences.md

- `GET /api/v3/notification/preferences` - Serves the V3 preference matrix.
- `POST /api/v3/notification/preferences` - Bulk-updates the changed subset of the matrix.

### Orb Categories

Taxonomy labels for organizing and discovering orbs in the registry.

Full detail: https://circleci.com/docs/api/v3/orb-categories.md

- `GET /api/v3/orb/categories` - Returns all orb categories with pagination.

### Orb Packages

Reusable configuration packages published to the orb registry. Each orb belongs to a namespace and has one or more versioned releases.

Full detail: https://circleci.com/docs/api/v3/orb-packages.md

- `GET /api/v3/orb/packages` - Returns a list of packages limited by the given filter.
- `POST /api/v3/orb/packages` - Creates a new orb package in the given namespace.
- `GET /api/v3/orb/packages/:id` - Retrieves a single package by its ID.
- `POST /api/v3/orb/packages/import` - Creates a new orb package via admin import.
- `POST /api/v3/orb/packages/validate` - Checks whether the given orb YAML is valid.
- `POST /api/v3/orb/packages/:id/add-category` - Adds a category to the package.
- `POST /api/v3/orb/packages/:id/remove-category` - Removes a category from a package.
- `POST /api/v3/orb/packages/:id/set-listed` - Marks a package as listed or unlisted.

### Orb Versions

Individual published releases of an orb, identified by semantic version. Each version contains the orb's source configuration.

Full detail: https://circleci.com/docs/api/v3/orb-versions.md

- `GET /api/v3/orb/versions` - Returns orb versions matching the given filters.
- `POST /api/v3/orb/versions` - Creates a new orb version with the given YAML source.
- `GET /api/v3/orb/versions/:id` - Retrieves a single orb version by its ID.
- `POST /api/v3/orb/versions/import` - Creates a new orb version via admin import.
- `POST /api/v3/orb/versions/:id/promote` - Promote a orb version.
- `GET /api/v3/orb/versions/:id/source` - Returns the raw YAML source of an orb version as text/plain.

### Orgs

Organizations are the top-level account entity. All projects, pipelines, and billing belong to an org.

Full detail: https://circleci.com/docs/api/v3/orgs.md

- `GET /api/v3/orgs` - Resolves orgs matching the given filters.
- `GET /api/v3/orgs/:id` - Fetches an org by its UUID.
- `GET /api/v3/orgs/:id/settings` - Returns settings for an org.
- `POST /api/v3/orgs/:id/update-settings` - Modifies settings for an org.

### Pipelines

Pipeline definitions describe how to build, test, and deploy a project.

Full detail: https://circleci.com/docs/api/v3/pipelines.md

- `GET /api/v3/pipelines` - Lists a project's pipelines, including its synthetic OAuth pipeline.
- `POST /api/v3/pipelines` - Creates a pipeline (config source) under the project named by project_id.
- `GET /api/v3/pipelines/:id` - Gets a pipeline by ID.
- `DELETE /api/v3/pipelines/:id` - Deletes a pipeline by ID.
- `POST /api/v3/pipelines/:id/update` - Partially updates a pipeline by ID.

### Projects

Projects represent a source code repository connected to CircleCI. A project typically contains pipelines, environment variables, and settings.

Full detail: https://circleci.com/docs/api/v3/projects.md

- `GET /api/v3/projects` - Resolves projects matching the given filters.
- `GET /api/v3/projects/:id` - Fetches a project by its UUID.
- `GET /api/v3/projects/:id/environment-variables` - Returns environment variables for a project.
- `POST /api/v3/projects/:id/environment-variables` - Sets a project environment variable.
- `POST /api/v3/projects/:id/rollback` - Rolls a deployed component back to an earlier version.
- `GET /api/v3/projects/:id/settings` - Returns settings for a project.
- `POST /api/v3/projects/:id/update-settings` - Modifies settings for a project.
- `DELETE /api/v3/projects/:id/environment-variables/:name` - Removes a project environment variable.

### Provider Branches

VCS provider branches available to a project.

Full detail: https://circleci.com/docs/api/v3/provider-branches.md

- `GET /api/v3/provider/branches` - Lists branches for a repository.

### Provider Connections

Connections between an organization and a VCS provider. Setup returns where to send the user; nothing is connected until they finish at the provider.

Full detail: https://circleci.com/docs/api/v3/provider-connections.md

- `GET /api/v3/provider/connections` - Lists an organization's provider connections.
- `POST /api/v3/provider/connections/setup` - Starts connecting a provider to an organization.

### Provider Repositories

Repositories an organization's provider installation can reach, as the calling user sees them. Scoped via filter[org_id] and filter[provider]; cursor-paged.

Full detail: https://circleci.com/docs/api/v3/provider-repositories.md

- `GET /api/v3/provider/repositories` - Lists repositories for an installation.

### Runner Agents

Self-hosted runner agents connected to a resource class. Read-only, scoped via filter[resource_class].

Full detail: https://circleci.com/docs/api/v3/runner-agents.md

- `GET /api/v3/runner/agents` - Lists the runner agents for a resource class.

### Runner Resource Classes

Self-hosted runner resource classes — the pool identifier agents register against and jobs request work from.

Full detail: https://circleci.com/docs/api/v3/runner-resource-classes.md

- `GET /api/v3/runner/resource-classes` - Lists the runner resource classes for an organization.
- `POST /api/v3/runner/resource-classes` - Creates a runner resource class in the organization.
- `GET /api/v3/runner/resource-classes/:id` - Returns a single runner resource class by id.
- `DELETE /api/v3/runner/resource-classes/:id` - Deletes a runner resource class.
- `POST /api/v3/runner/resource-classes/:id/update` - Performs a partial update of the mutable fields.

### Runner Tokens

Authentication tokens for self-hosted runners.

Full detail: https://circleci.com/docs/api/v3/runner-tokens.md

- `GET /api/v3/runner/tokens` - Lists the tokens for a runner resource class.
- `POST /api/v3/runner/tokens` - Creates a runner resource-class token.
- `GET /api/v3/runner/tokens/:id` - Returns a single runner resource-class token by id.
- `DELETE /api/v3/runner/tokens/:id` - Deletes a runner resource-class token by id.

### Runs

Runs record each trigger firing and group the workflows they produce. A run carries VCS context, parameter overrides, and pre-workflow errors.

Full detail: https://circleci.com/docs/api/v3/runs.md

- `GET /api/v3/runs` - Returns a paginated list of runs.
- `POST /api/v3/runs` - Fires a run for the pipeline named by pipeline_id, returning the created
- `GET /api/v3/runs/:id` - Retrieve a single run by its ID.
- `GET /api/v3/runs/facet-values` - Returns a paginated list of distinct values for a single run facet within one project.
- `POST /api/v3/runs/search` - Search a run.
- `POST /api/v3/runs/facet-values/search` - Returns a paginated list of distinct values for a single run facet across one or more projects.

### Sidecar Commands

Commands sent to a sidecar instance for execution.

Full detail: https://circleci.com/docs/api/v3/sidecar-commands.md

- `GET /api/v3/sidecar/commands/:id` - Retrieve a single sidecar command by its ID.
- `GET /api/v3/sidecar/commands/:id/output` - Streams a command's output as Server-Sent Events.

### Sidecar Instances

Lightweight microVM environments that mirror a project's stack for inner-loop validation.

Full detail: https://circleci.com/docs/api/v3/sidecar-instances.md

- `GET /api/v3/sidecar/instances` - List sidecar instances.
- `POST /api/v3/sidecar/instances` - Create a new sidecar instance.
- `GET /api/v3/sidecar/instances/:id` - Retrieve a single sidecar instance by its ID.
- `DELETE /api/v3/sidecar/instances/:id` - Delete a sidecar instance.
- `POST /api/v3/sidecar/instances/prune` - Deletes caller-owned sidecar instances in orgID.
- `POST /api/v3/sidecar/instances/:id/exec` - Starts a command asynchronously and returns 202.
- `POST /api/v3/sidecar/instances/:id/ssh/add-key` - Adds an ssh key to the instance.

### Sidecar Snapshots

Point-in-time snapshots of a sidecar instance's filesystem and state.

Full detail: https://circleci.com/docs/api/v3/sidecar-snapshots.md

- `GET /api/v3/sidecar/snapshots` - List sidecar snapshots.
- `POST /api/v3/sidecar/snapshots` - Create a new sidecar snapshot.
- `GET /api/v3/sidecar/snapshots/:id` - Retrieve a single sidecar snapshot by its ID.

### Signing Certificates

Apple code-signing certificates used to sign iOS builds.

Full detail: https://circleci.com/docs/api/v3/signing-certificates.md

- `GET /api/v3/signing/certificates` - Lists the iOS signing certificates for an organization.
- `POST /api/v3/signing/certificates` - Uploads an iOS signing certificate to an organization.
- `GET /api/v3/signing/certificates/:id` - Returns a single iOS signing certificate by ID.
- `DELETE /api/v3/signing/certificates/:id` - Deletes an iOS signing certificate.

### Signing Configs

iOS signing configurations pairing a certificate with provisioning profiles.

Full detail: https://circleci.com/docs/api/v3/signing-configs.md

- `GET /api/v3/signing/configs` - Lists the iOS signing configurations for an organization.
- `POST /api/v3/signing/configs` - Creates an iOS signing configuration for an organization.
- `DELETE /api/v3/signing/configs/:id` - Deletes an iOS signing configuration.
- `POST /api/v3/signing/configs/:id/remove-profile` - Removes a provisioning profile from an iOS signing configuration.
- `POST /api/v3/signing/configs/:id/update-profile` - Updates a provisioning profile in an iOS signing configuration.

### Tool Releases

Released versions of the tools CircleCI distributes, such as circleci-cli and chunk-cli. Requires filter[tool], whose values are the tools' GitHub repository names, and returns that tool's latest release.

Full detail: https://circleci.com/docs/api/v3/tool-releases.md

- `GET /api/v3/tool/releases` - List tool releases.

### Triggers

A trigger defines what causes a pipeline to run: a VCS event, a custom webhook, or a cron schedule.

Full detail: https://circleci.com/docs/api/v3/triggers.md

- `GET /api/v3/triggers` - Lists a project's triggers.
- `POST /api/v3/triggers` - Creates a trigger under the pipeline named by pipeline_id.
- `GET /api/v3/triggers/:id` - Gets a trigger by ID.
- `DELETE /api/v3/triggers/:id` - Deletes a trigger by ID.
- `POST /api/v3/triggers/:id/update` - Partially updates a trigger by ID.

### Usage

Usage and billing data exports.

Full detail: https://circleci.com/docs/api/v3/usage.md

- `POST /api/v3/usage/exports`
- `GET /api/v3/usage/exports/:id`

### Users

Authenticated identities (human or machine). Use ?filter[user_id]=me to resolve the authenticated identity.

Full detail: https://circleci.com/docs/api/v3/users.md

- `GET /api/v3/users` - Returns a list of users limited by filter query parameters.

### Workflows

Workflows organise jobs into a dependency graph. A run may produce multiple workflows that execute in parallel or sequence.

Full detail: https://circleci.com/docs/api/v3/workflows.md

- `GET /api/v3/workflows` - Lists the workflows in a run.
- `GET /api/v3/workflows/:id` - Retrieve a single workflow by its ID.
- `POST /api/v3/workflows/:id/cancel` - Requests cancellation of a workflow.
- `POST /api/v3/workflows/:id/rerun` - Reruns an existing workflow, creating and returning a new workflow.