Every V3 endpoint, its parameters and the statuses it can answer with. The
machine-readable description of this API is
/fullopenapi.yaml
(JSON), catalogued at
/.well-known/api-catalog.
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.
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.
Analysis
Credit spend aggregated by job, workflow or pipeline.
POST /api/v3/analysis/charges
Returns entities ranked by what they were charged.
EXPERIMENTAL — This endpoint is experimental and may change without notice. Field names, request and response shapes, and pagination semantics are not yet stable. Do not depend on this endpoint in production clients.
Returns a paginated list of charge totals scoped to one or more projects within a time window. The required analysis field selects what charges are grouped by: charge.job, charge.workflow or charge.pipeline.
Each result is one entity name within one project, carrying the credits it was charged, the number of runs those credits are spread across, and the credits per run. A run is one instance of the entity: charge.job counts jobs, charge.workflow counts workflows, charge.pipeline counts pipelines.
Other dimensions of a charge are filters rather than groupings, so slice by them through filter: actor.id, actor.external_slug, resource.class and charge.type, alongside job, workflow and pipeline values.
The optional order_by field accepts an expression of the form [asc|desc]. The direction is optional and falls back to a per-field default. When order_by is omitted or empty, results are sorted by credits desc. Supported fields and their default directions: credits (desc), runs (desc), credits_per_run (desc), name (asc).
EXPERIMENTAL — This endpoint is experimental and may change without notice. Field names, request and response shapes, and pagination semantics are not yet stable. Do not depend on this endpoint in production clients.
Returns a paginated list of aggregated job results scoped to one or more projects within a time window. Each result represents a unique job (identified by project + workflow + job name) and includes per-job duration quantiles, success rate, and distinct test counts across the window.
The optional order_by field accepts an expression of the form [asc|desc]. The direction is optional and falls back to a per-field default. When order_by is omitted or empty, results are sorted by name asc. Supported fields and their default directions: name (asc), workflow_name (asc), duration (desc), test_count (desc), flaky_test_count (desc), success_rate (desc).
EXPERIMENTAL — This endpoint is experimental and may change without notice. Field names, request and response shapes, and pagination semantics are not yet stable. Do not depend on this endpoint in production clients.
Returns a paginated list of aggregated test results scoped to one or more projects within a time window. Each result represents a unique test (identified by project + workflow + job + classname + file + name) and includes per-test success rate and average duration over the window.
total_count is the number of non-skipped executions of the test in the window. flaky_count is the number of those executions that failed or errored within a pipeline where the same test also passed, matching the test_flake.pipeline metric. Skipped executions are excluded from every attribute, so a test that only ever skipped in the window is omitted.
The optional order_by field accepts an expression of the form [asc|desc]. The direction is optional and falls back to a per-field default. When order_by is omitted or empty, results are sorted by name asc. Supported fields and their default directions: name (asc), job_name (asc), duration (desc), flaky_count (desc), success_rate (desc).
Returns entities ranked by the resources they consumed.
EXPERIMENTAL — This endpoint is experimental and may change without notice. Field names, request and response shapes, and pagination semantics are not yet stable. Do not depend on this endpoint in production clients.
Returns a paginated list of resource usage scoped to one or more projects within a time window, which selects the jobs that completed inside it. The required analysis field picks the granularity: usage.job, usage.workflow or usage.pipeline.
Each result is one entity name within one project. avg_cpu_used and avg_memory_bytes are means over that entity's samples, so they weight by run duration; peak_cpu_used and peak_memory_bytes are the largest single sample, not a concurrent total. cpu_utilization and ram_utilization are those means over what was allocated, where 1 is fully consumed and a low value means over-provisioned. network_bytes_received and network_bytes_transmitted are totals across runs. runs counts the entity's instances — jobs, workflows or pipelines per the granularity.
A pipeline is named only by its configuration, so usage.pipeline reports pipelines that carry no name together under an empty name.
Other dimensions are filters rather than groupings, so slice by them through filter: resource.class, resource.executor, resource.cpu (cores), resource.ram (mebibytes, unlike the *_memory_bytes attributes), parallel_execution.number, and job, workflow and pipeline values.
The optional order_by takes [asc|desc], defaulting to peak_memory_bytes desc. Supported fields and their default directions: peak_memory_bytes (desc), avg_memory_bytes (desc), peak_cpu_used (desc), avg_cpu_used (desc), cpu_utilization (asc), ram_utilization (asc), network_bytes_received (desc), network_bytes_transmitted (desc), runs (desc), name (asc). The utilizations default ascending because the least utilized entities are the over-provisioned ones.
Marketplace catalog of available products and add-ons.
GET /api/v3/catalog/offerings
Responses
200 OK
401 Provide a valid Authorization header.
403 You do not have access to this resource.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
Configs
Configuration compilation and validation.
POST /api/v3/configs/compile
Compiles the supplied pipeline config, expanding orbs and resolving parameters.
A config that fails to compile is reported as outcome "failed" with the reasons in meta.messages - still HTTP 200, since the request itself succeeded. The error envelope is reserved for request-level failures (malformed body, bad org, unauthorized).
Returns an organization's deploy components, ordered by name.
filter[org_id] is required — there is no unscoped listing of components across organizations. filter[project_id] optionally narrows the result to the components owned by one CircleCI project. Results are paginated with page[limit] and page[cursor].
EXPERIMENTAL — this endpoint is experimental and may change without notice. Field names and response shapes are not yet stable, and the deploy API as a whole is still under review. Do not depend on it in production clients.
Parameters
filter[org_id] uuid, required
filter[project_id] uuid
page[cursor] string
page[limit] int
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 Not Found
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
503 Service unavailable.
GET /api/v3/deploy/components/:id
Returns a single deploy component by id.
A component the caller may not view is reported as not found, so the response does not reveal whether the id exists.
EXPERIMENTAL — this endpoint is experimental and may change without notice. Field names and response shapes are not yet stable, and the deploy API as a whole is still under review. Do not depend on it in production clients.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested components does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
503 Service unavailable.
GET /api/v3/deploy/components/:id/versions
Returns a component's versions, most recently deployed first.
Versions stay a sub-collection of their component because they have no identity of their own: a version is keyed by its name and the component instance it was deployed to, so collection items carry no id. filter[environment_id] narrows the result to one deploy environment. Results are paginated with page[limit] and page[cursor].
EXPERIMENTAL — this endpoint is experimental and may change without notice. Field names and response shapes are not yet stable, and the deploy API as a whole is still under review. Do not depend on it in production clients.
Parameters
id uuid, required - The id.
filter[environment_id] uuid
page[cursor] string
page[limit] int
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested components does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
503 Service unavailable.
Deploy Config Suggestions
Async requests to validate a CircleCI config and generate a suggested deploy config.
POST /api/v3/deploy/config-suggestions
Validates a CircleCI config and asynchronously
generates a suggested config of the requested kind (deploy markers, deploy pipeline, or rollback pipeline). It stores the request and returns a 202 with a request ID; the client polls GET .../:id until phase=ended.
Returns the status of an async config suggestion request.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested config-suggestions does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
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].
GET /api/v3/deploy/deployments
Returns an organization's deployments, most recently created first.
filter[org_id] is required — there is no unscoped listing of deployments across organizations, and the caller's permission to read that organization's deployments is what authorizes the request. The remaining filters narrow the result within the organization: by project, component, environment, the job that ran the deployment, a label, and a created-at window via filter[from] and filter[to].
Results are paginated with page[limit] and page[cursor]; the cursor carries its own direction, so page.prev walks back towards newer deployments.
EXPERIMENTAL — this endpoint is experimental and may change without notice. Field names and response shapes are not yet stable, and the deploy API as a whole is still under review. Do not depend on it in production clients.
Parameters
filter[label] string
filter[org_id] uuid, required
page[cursor] string
page[limit] int
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 Not Found
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
503 Service unavailable.
Deploy Diff Summaries
Async requests to generate a human-readable summary of a code diff.
Release tracker environments for deployment management.
GET /api/v3/deploy/environments
Returns an organization's deploy environments, ordered by name.
filter[org_id] is required — there is no unscoped listing of environments across organizations. Results are paginated with page[limit] and page[cursor].
EXPERIMENTAL — this endpoint is experimental and may change without notice. Field names and response shapes are not yet stable, and the deploy API as a whole is still under review. Do not depend on it in production clients.
Parameters
filter[org_id] uuid, required
page[cursor] string
page[limit] int
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 Not Found
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
503 Service unavailable.
GET /api/v3/deploy/environments/:id
Returns a single deploy environment by id.
An environment the caller may not view is reported as not found, so the response does not reveal whether the id exists.
EXPERIMENTAL — this endpoint is experimental and may change without notice. Field names and response shapes are not yet stable, and the deploy API as a whole is still under review. Do not depend on it in production clients.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested environments does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
503 Service unavailable.
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.
GET /api/v3/deploy/settings
Returns a project's deploy settings.
Deploy settings are a singleton per project rather than an independently addressable resource, so they are selected with a required filter[project_id] instead of a path id, and the returned data.id is the project's own UUID.
A project that has never had deploy settings saved reports empty settings rather than a 404, matching the V2 behaviour: not having configured a deploy pipeline is a normal state, not a missing resource. A project the caller may not view is reported as not found.
EXPERIMENTAL — this endpoint is experimental and may change without notice. Field names and response shapes are not yet stable, and the deploy API as a whole is still under review. Do not depend on it in production clients.
Parameters
filter[project_id] uuid, required
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 Not Found
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
503 Service unavailable.
Jobs
Individual units of work within a workflow. Each job runs in its own execution environment and produces artifacts, test results, and logs.
GET /api/v3/jobs
Lists the jobs in a workflow.
Parameters
filter[workflow_id] uuid, required
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 Workflow not found.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/jobs/:id
Fetches a single job, including its steps and parallel executions.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested jobs does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/jobs/:id/artifacts
Lists the artifacts produced by a job's parallel executions.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested jobs does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/jobs/:id/resource-usage
Returns a job's recorded resource usage per parallel execution.
Each execution reports ordered CPU, memory and network samples taken interval_ms apart, alongside the resource class the job was dispatched to. Samples carry no timestamps: the first sample is the first collection tick after the execution started.
Only Docker executions record samples, so machine and runner jobs return an empty parallel_executions list. Recordings expire after 90 days, and an execution that recorded nothing is absent from the list rather than empty, so a missing execution is not an execution that did not run.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested jobs does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/jobs/:id/stderr
Returns the stderr of a job step for a given parallel execution.
Parameters
id uuid, required - The id.
filter[execution] int, required
filter[step_num] int, required
Responses
204 No Content
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested jobs does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/jobs/:id/stdout
Returns the stdout of a job step for a given parallel execution.
Parameters
id uuid, required - The id.
filter[execution] int, required
filter[step_num] int, required
Responses
204 No Content
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested jobs does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/jobs/:id/tests
Returns a job's structured test results as JSON Lines.
Parameters
id uuid, required - The id.
Responses
204 No Content
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested jobs does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/jobs/:id/stdout/condensed
Returns a step's stdout condensed to its most error-relevant lines, suitable for AI-agent consumption.
Parameters
id uuid, required - The id.
filter[execution] int, required
filter[step_num] int, required
Responses
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested jobs does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
Metric
Time-bucketed count metrics (test result counts and test flake counts) over a time window.
POST /api/v3/metric/counts
Returns time-bucketed counts for a named metric.
EXPERIMENTAL — This endpoint is experimental and may change without notice. Field names, request and response shapes, and supported metrics are not yet stable. Do not depend on this endpoint in production clients.
Returns count metrics (test result counts and test flake counts) over a time window, split into fixed-width buckets. Each bucket contains one or more groups when group_by dimensions are supplied. Each group's key is a positional array whose entries align 1:1 with the request's group_by expressions (so key[i] is the value for group_by[i]), and is null when no group_by is supplied.
Buckets with no matching rows are omitted rather than zero-filled — including the single bucket of an interval=none request over an empty window, which returns an empty buckets array. Clients should treat an absent bucket as zero.
Returns time-bucketed distribution metrics for a named metric.
EXPERIMENTAL — This endpoint is experimental and may change without notice. Field names, request and response shapes, and supported metrics are not yet stable. Do not depend on this endpoint in production clients.
Returns distribution metrics (e.g. test result duration percentiles) over a time window, split into fixed-width buckets. Each bucket contains one or more groups when group_by dimensions are supplied. Each group's key is a positional array whose entries align 1:1 with the request's group_by expressions (so key[i] is the value for group_by[i]), and is null when no group_by is supplied.
Buckets with no matching rows are omitted rather than zero-filled — including the single bucket of an interval=none request over an empty window, which returns an empty buckets array. An absent bucket means no observations in that slice; do not invent zero averages or percentiles.
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.
GET /api/v3/notification/links
Lists the authenticated caller's external identity links.
EXPERIMENTAL — This endpoint is experimental and may change without notice. Field names, request and response shapes, and pagination semantics are not yet stable. Do not depend on this endpoint in production clients.
filter[user_id] is required ("me" or the caller's own UUID). filter[connection_type] is optional (omitted lists all known connection types); filter[team_id] is optional and narrows results to a single external scope.
Parameters
filter[connection_type] string
filter[team_id] string
filter[user_id] string, required
Responses
200 OK
400 Filter[user_id] must be "me" or a user UUID
401 Provide a valid Authorization header.
403 You do not have access to this resource.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
DELETE /api/v3/notification/links
Removes a single external identity link.
EXPERIMENTAL — This endpoint is experimental and may change without notice. Field names and request shape are not yet stable. Do not depend on this endpoint in production clients.
filter[user_id] ("me" or the caller's own UUID), filter[connection_type], and filter[team_id] are all required — together they form the CIAM link key. Idempotent: returns 204 whether or not a matching link exists.
Parameters
filter[connection_type] string, required
filter[team_id] string, required
filter[user_id] string, required
Responses
400 Unsupported connection_type
401 Provide a valid Authorization header.
403 You do not have access to this resource.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
Notification Preferences
Per-user and per-project notification preference matrix. Read the matrix or bulk-toggle entries; scoped via filter[scope]=user|project.
GET /api/v3/notification/preferences
Serves the V3 preference matrix.
filter[scope] selects user or project scope; project scope also requires filter[project_id] and filter[org_id].
Parameters
filter[org_id] string, required
filter[project_id] string, required
filter[scope] string, required
Responses
200 OK
400 Filter[scope] must be "user" or "project"
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 Not Found
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/notification/preferences
Bulk-updates the changed subset of the matrix.
It returns the refreshed matrix. Partial and non-idempotent, hence POST. Scope comes from data.attributes.scope; project scope also requires project + org references.
400 Either 'segment' or 'semantic_version' must be provided.
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested versions does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/orb/versions/:id/source
Returns the raw YAML source of an orb version as text/plain.
Parameters
id uuid, required - The id.
Responses
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested versions does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
Orgs
Organizations are the top-level account entity. All projects, pipelines, and billing belong to an org.
GET /api/v3/orgs
Resolves orgs matching the given filters.
filter[slug] is optional. With it, a single org is resolved by its slug; a slug matching no org is an empty collection rather than a 404. Without it, the orgs the calling user belongs to are listed.
Parameters
filter[slug] string
page[cursor] string
page[limit] int
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/orgs/:id
Fetches an org by its UUID.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested orgs does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/orgs/:id/settings
Returns settings for an org.
Settings are a singleton sub-resource of the org, so the data entity does not include an id - the org's id is in the path.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested orgs does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/orgs/:id/update-settings
Modifies settings for an org.
Settings are a singleton sub-resource of the org, so the data entity does not include an id - the org's id is in the path.
The optional filter[project_id] query parameter scopes the lookup; it is required to resolve synthetic OAuth pipelines, which have no stored row and are derived from the project.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested pipelines does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
DELETE /api/v3/pipelines/:id
Deletes a pipeline by ID.
The optional filter[project_id] query parameter scopes the lookup; it is required to identify synthetic OAuth pipelines, which have no stored row and are derived from the project.
Parameters
id uuid, required - The id.
Responses
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested pipelines does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/pipelines/:id/update
Partially updates a pipeline by ID.
Only the fields present in the request body (name, description, config.file_path) are changed. The optional filter[project_id] query parameter scopes the lookup; synthetic OAuth pipelines have no stored row and cannot be updated.
Projects represent a source code repository connected to CircleCI. A project typically contains pipelines, environment variables, and settings.
GET /api/v3/projects
Resolves projects matching the given filters.
Exactly one of filter[slug] (resolving a single project) or filter[org_id] (listing an org's projects) must be supplied. Neither an unfiltered list nor both filters together is supported, so either is a 400.
filter[name] is optional and applies only to the filter[org_id] form, where it narrows the org's projects by a case-insensitive name search. Combining it with filter[slug] is a 400.
An org that does not exist, or that the caller cannot see, is a 404. A slug that matches no project is an empty collection.
Notes on pagination:
Parameters
filter[name] string
filter[org_id] uuid
filter[slug] string
page[cursor] string
page[limit] int
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/projects/:id
Fetches a project by its UUID.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested projects does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/projects/:id/environment-variables
Returns environment variables for a project.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested projects does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/projects/:id/environment-variables
Sets a project environment variable.
An environment variable is keyed by name within its project, so the data entity does not include an id.
Parameters
id uuid, required - The id.
Request body
{
"name": "string",
"value": "string"
}
Responses
201 Created
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested projects does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/projects/:id/rollback
Rolls a deployed component back to an earlier version.
The component and the environment identify what is running the version being rolled back; current_version must match the version deployed there, so a caller working from stale state cannot roll back a version that has since been superseded.
How the rollback runs depends on the project's deploy settings: a project with a rollback pipeline configured gets a pipeline run, and one without gets a restore-version command sent to the release agent deployed in that environment. data.id is that run or that command and rollback_type says which, since the two are polled in different places.
The response is 200 rather than 202 because data.id is a handle to work in progress, not a resource newly created at a V3 address there would be a Location to point at.
A component or environment the caller may not deploy to is reported as not found, as is a component and environment that do not describe one deployed thing in this project, so the response does not reveal whether the ids exist.
EXPERIMENTAL — this endpoint is experimental and may change without notice. Field names and response shapes are not yet stable, and the deploy API as a whole is still under review. Do not depend on it in production clients.
Requires filter[org_id] (the organization), filter[provider] (the integration provider), and filter[repo_id] (the external repository id). Supports cursor pagination via page[limit] and page[cursor]. The cursor encodes the limit from the originating request; sending page[limit] alongside page[cursor] is rejected with 400.
Parameters
filter[org_id] uuid, required
filter[provider] string, required
filter[repo_id] string, required
page[cursor] string
page[limit] int
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
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.
GET /api/v3/provider/connections
Lists an organization's provider connections.
Returns every connection that authorizes CircleCI to act for the organization — a GitHub App installation, a GitHub Server installation, an Origin installation — with the provider's live view of each. Custom webhook connections are not included. Requires filter[org_id] and view-org on that organization.
Each item always carries its stored fields. The provider is also asked for the installation as it currently stands and for the calling user's identity there; either failing degrades that item rather than the response, populating connection_error or authorization_error and omitting the fields it could not fill. An organization with no connections is an empty list, not a 404.
A connection appears only once the customer has finished authorizing it at the provider. A setup that has been started and not completed is not listed, and is indistinguishable here from one that was never started.
Parameters
filter[org_id] uuid, required
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/provider/connections/setup
Starts connecting a provider to an organization.
Returns where to send the user to finish the connection at the provider. next_step "redirect" carries the url that connects an app CircleCI has already registered with the provider; "register" carries a manifest and state_token for the user to register one first. Nothing is connected when this returns. Requires filter[org_id] and manage-org on that organization. Each call mints and stores a fresh state token, valid for one hour, so this endpoint is deliberately not idempotent.
Repositories an organization's provider installation can reach, as the calling user sees them. Scoped via filter[org_id] and filter[provider]; cursor-paged.
GET /api/v3/provider/repositories
Lists repositories for an installation.
Returns the repositories accessible for the specified organization's installation. Requires filter[org_id] and filter[provider], which must be one of github_app, github_server or origin. Supports cursor pagination via page[limit] and page[cursor]. The cursor encodes the limit from the originating request; sending page[limit] alongside page[cursor] with a different value is rejected with 400.
What "accessible" means depends on the provider. For github_app and github_server the results are what the calling user's own credential can see, so two members of one organization may get different lists. Origin authorizes by installation rather than by user, so every member with view-org gets the whole installation.
Origin reports neither repository visibility nor a web URL, so origin items omit html_url and report is_private as true — a conservative default rather than a value read from the provider.
Parameters
filter[org_id] uuid, required
filter[provider] string, required
page[cursor] string
page[limit] int
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
Runner Agents
Self-hosted runner agents connected to a resource class. Read-only, scoped via filter[resource_class].
GET /api/v3/runner/agents
Lists the runner agents for a resource class.
Parameters
filter[resource_class] string, required
page[cursor] string
page[limit] int
Responses
200 OK
400 Resource_class is not valid.
401 Provide a valid Authorization header.
403 You do not have access to this resource.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
503 Unable to determine agent status.
Runner Resource Classes
Self-hosted runner resource classes — the pool identifier agents register against and jobs request work from.
GET /api/v3/runner/resource-classes
Lists the runner resource classes for an organization.
Parameters
filter[org_id] uuid, required
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
503 Permission check unavailable.
POST /api/v3/runner/resource-classes
Creates a runner resource class in the organization.
Returns a single runner resource-class token by id.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested tokens does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
503 Permission check unavailable.
DELETE /api/v3/runner/tokens/:id
Deletes a runner resource-class token by id.
Parameters
id uuid, required - The id.
Responses
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested tokens does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
503 Permission check unavailable.
Runs
Runs record each trigger firing and group the workflows they produce. A run carries VCS context, parameter overrides, and pre-workflow errors.
GET /api/v3/runs
Returns a paginated list of runs.
The returned list can be for a single project, or the caller's own recent runs when filter[user_id]=me.
Parameters
filter[project_id] uuid
filter[user_id] string
page[cursor] string
page[limit] int
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 Project not found or permission denied.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/runs
Fires a run for the pipeline named by pipeline_id, returning the created
run. The optional filter[project_id] scopes the pipeline to a project directly (mirroring Get/Delete); DB-backed pipelines omit it and derive the project from pipeline_id.
Returns a paginated list of distinct values for a single run facet within one project.
EXPERIMENTAL — This endpoint is experimental and may change without notice. Field names, request and response shapes, and pagination semantics are not yet stable. Do not depend on this endpoint in production clients.
Values are ordered by most-recently-seen (the most recent pipeline that carried the value). Supported facet keys are actor.id, pipeline.status, pipeline.phase, pipeline.current_outcome, and indexed pipeline values (for example pipeline.git.branch).
Parameters
filter[facet] string, required
filter[project_id] uuid, required
page[cursor] string
page[limit] int
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 Project not found or permission denied.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/runs/search
Search a run.
The optional include field requests nested entities on each run. Allowed values are workflows (truncated nested workflows) and workflows.jobs (workflows plus a truncated nested jobs list per workflow). Unknown values are rejected with 400. When include is omitted or empty, attributes.workflows is omitted from each item. Nested workflow lists are capped at 5 items and nested job lists at 20; is_truncated is true when more exist, and total_count / count_by_phase / count_by_outcome cover the full uncapped set.
Returns a paginated list of distinct values for a single run facet across one or more projects.
EXPERIMENTAL — This endpoint is experimental and may change without notice. Field names, request and response shapes, and pagination semantics are not yet stable. Do not depend on this endpoint in production clients.
Values are ordered by most-recently-seen (the most recent pipeline that carried the value). Supported facet keys are actor.id, pipeline.status, pipeline.phase, pipeline.current_outcome, and indexed pipeline values (for example pipeline.git.branch).
The optional filter expression pre-filters which pipelines contribute values (same expression grammar as api/v3/runs/search). The optional matches string is a case-insensitive substring match against the facet values themselves. When scope.from or scope.to are omitted, the same default two-week window used by other v3 search endpoints is applied.
Commands sent to a sidecar instance for execution.
GET /api/v3/sidecar/commands/:id
Retrieve a single sidecar command by its ID.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested commands does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
504 Sidecar did not respond in time
GET /api/v3/sidecar/commands/:id/output
Streams a command's output as Server-Sent Events.
Output arrives as stdout and stderr events whose data is the base64 of the raw bytes, so carriage returns, ANSI escapes and invalid UTF-8 reach the client exactly as the command wrote them. A start event opens the stream and : comments keep it warm while a command is silent.
Every event carries an opaque id. Send the last one back in the Last-Event-ID header to resume precisely where a dropped connection stopped; the stdout_offset and stderr_offset query parameters do the same for callers that cannot set headers. Last-Event-ID wins if both are supplied.
The stream ends with exactly one exit or error event, or with nothing at all. Nothing at all means the connection was interrupted and the client should resume — it is the only way to distinguish a finished command from a truncated stream.
Parameters
id uuid, required - The id.
stderr_offset string
stdout_offset string
Responses
200 OK
400 Invalid stdout_offset
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested commands does not exist.
410 Sidecar is out of date; delete and recreate with: chunk sidecar create
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
502 Could not reach the sidecar
504 The sidecar stopped responding
Sidecar Instances
Lightweight microVM environments that mirror a project's stack for inner-loop validation.
Removes a provisioning profile from an iOS signing configuration.
Parameters
id uuid, required - The id.
Request body
{
"profile_id": "uuid"
}
Responses
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested configs does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/signing/configs/:id/update-profile
Updates a provisioning profile in an iOS signing configuration.
Parameters
id uuid, required - The id.
Request body
{
"blob": "string",
"file_name": "string"
}
Responses
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested configs does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
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.
GET /api/v3/tool/releases
List tool releases.
Responses
401 Provide a valid Authorization header.
403 You do not have access to this resource.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
Triggers
A trigger defines what causes a pipeline to run: a VCS event, a custom webhook, or a cron schedule.
GET /api/v3/triggers
Lists a project's triggers.
At least one of filter[project_id] or filter[pipeline_id] is required; both may be given to require triggers to match both. The result includes the project's synthetic OAuth trigger whenever it satisfies the supplied filters (a list not scoped by pipeline, or a filter[pipeline_id] pointing at the synthetic pipeline). A synthetic pipeline id cannot be resolved from the id alone, so a pipeline-only request for it returns 404; supply project_id to surface the synthetic trigger.
Parameters
filter[pipeline_id] uuid
filter[project_id] uuid
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/triggers
Creates a trigger under the pipeline named by pipeline_id.
Returns the full created entity (shape-identical to Get, plus the one-time webhook secret).
The optional filter[project_id] query parameter scopes the lookup; it is required to resolve synthetic OAuth triggers, which have no stored row and are derived from the project.
Parameters
id uuid, required - The id.
Responses
200 OK
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested triggers does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
DELETE /api/v3/triggers/:id
Deletes a trigger by ID.
The optional filter[project_id] query parameter scopes the lookup; it is required to resolve synthetic OAuth triggers, which have no stored row and are derived from the project.
Parameters
id uuid, required - The id.
Responses
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested triggers does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/triggers/:id/update
Partially updates a trigger by ID.
The optional filter[project_id] query parameter scopes the lookup; it is required to resolve synthetic OAuth triggers.