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 average duration, success rate, and distinct test counts across the window.
flaky_test_count counts distinct tests that flaked, not flake occurrences. A test is flaky when it failed and passed within the same pipeline.
Results come from pre-aggregated data: whole UTC days are read from a day-grain aggregate and the partial days at either end of the window from an hour-grain one. The lower bound widens to the start of the hour it falls in, and the aggregates trail real time by roughly an hour.
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.
The window is half-open, [from, to): an execution starting exactly on from is included, one starting exactly on to is not.
total_count is the number of non-skipped executions of the test in the window. flaky_count is the number of recorded flakes: executions that failed within a pipeline where the same test also passed. It reports the same figure the test_flake.pipeline metric reports for the same test and window. Repeated failures within one job attempt are recorded as a single flake. Skipped executions are excluded from every attribute, so a test that only ever skipped in the window is omitted.
Results come from pre-aggregated data: whole UTC days are read from a day-grain aggregate and the partial days at either end of the window from an hour-grain one. The lower bound widens to the start of the hour it falls in, and the aggregates trail real time by roughly an hour.
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).
Restrictions that limit which projects, groups, or expressions may use a context.
GET /api/v3/context-restrictions
Lists every restriction applied to a context.
The context_id filter is required. A context that does not exist, or that the caller is not entitled to see, returns 404.
All three restriction types are listed together: project, expression and group. A project restriction carries a project reference and a group restriction carries a group reference, each with the subject's name where it can be resolved. An expression restriction has no subject reference — its match_pattern is the expression itself.
created_at is absent on restrictions for which no creation timestamp is recorded.
Parameters
filter[context_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/context-restrictions
Creates a restriction for the context referenced in the request body.
restriction_type is "project", "expression" or "group". match_pattern is the project id, the expression, or the id of the group permitted to use the context respectively. To permit every member of the owning org, use a group restriction whose match_pattern is the org id.
The created item carries the same subject reference the restriction list returns, with the subject id only; the list endpoint resolves subject names.
The context_id filter is required: restriction ids are only unique within a context, so the context must be named to identify the restriction and to authorise the delete.
Accepts the id of any restriction the list endpoint returns, of any type. For a group restriction that id is the group's id.
Parameters
id uuid, required - The id.
filter[context_id] uuid, required
Responses
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested context-restrictions does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
Contexts
Secret contexts that provide environment variables to jobs at runtime.
GET /api/v3/contexts
Lists the contexts owned by an organization.
The org_id filter is required. The optional name filter matches case-insensitively on any part of the context name and is applied upstream, so it also narrows what pagination walks.
include=restrictions embeds each context's group restrictions, with the group names, under the references key "context-restrictions" — the same shape the single-context read documents. That is what a caller rendering a list of contexts and who may use them needs, in one request.
Project and expression restrictions are not embedded here. They are addressable only one context at a time, so including them across a page would cost a lookup per context. Read those from the context-restrictions endpoint, or from the single-context read, which embeds every type.
The response carries the context itself. What restricts it is reported by the context-restrictions endpoint, and is embedded here under the references key "context-restrictions" only when the caller passes include=restrictions — every restriction type, each with the name of the project or group it points at.
Parameters
id uuid, required - The id.
include string
Responses
200 OK
400 Include accepts "restrictions" only.
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested contexts does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
DELETE /api/v3/contexts/:id
Deletes a context 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 contexts does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/contexts/:id/env-vars
Lists the environment variables of a context.
Values are never returned; each item carries truncated_value, the last four characters of the secret, so a caller can tell which value is in a slot. Items have no id — environment variables are addressed by name.
Parameters
id uuid, required - The id.
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 contexts does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
DELETE /api/v3/contexts/:id/env-vars
Deletes an environment variable from a context by name.
Parameters
id uuid, required - The id.
filter[name] string, required
Responses
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested contexts does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/contexts/:id/env-vars/set
Creates or updates an environment variable in a context.
Always responds 200 with the stored variable, whether or not it already existed. The returned item carries no id — environment variables are addressed by name — and no truncated_value.
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 Hooks
Ingest hooks that receive deploy validation payloads from an external monitoring provider and match them against the organization's active validation plans.
POST /api/v3/deploy/hooks/:id/validate
Receives validation webhook payloads from external monitoring providers.
Authenticate with an Authorization: Bearer header carrying an org-scoped deploy validation service token (CCIVWH_…), not a user API token. Upstream auth is optional on this route, so a request with no valid token is forwarded with no org context and rejected here with a 401 rather than being turned away at the gateway. A valid token resolves to the organization it was issued for. Auth that resolves to anything narrower than the org itself, a user token or a short lived PAT for instance, is rejected the same way.
The hook id in the path is an opaque identifier for the ingest hook — today the organization's own UUID — and must match the authenticated organization.
The body is the monitoring provider's own payload (Datadog, for example). Its schema is provider-specific and is not validated: a payload that matches no active validation plan, or that cannot be parsed at all, is still accepted. A 204 therefore means the webhook was received, not that a validation matched or that any plan changed state.
EXPERIMENTAL — this endpoint is experimental and may change without notice. Field names, request shapes and authentication semantics 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
204 No Content
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested hooks does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
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.
Groups
RBAC groups within an organization. Used to scope access to resources such as the contexts a group may execute.
GET /api/v3/groups
Lists the groups owned by an organization.
An optional filter[project_id] narrows results to groups that have a role grant on the given project and includes the role in the response attributes. This filter is only supported for standalone (circleci) orgs; legacy orgs are rejected by the backend.
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.
Parallel executions are numbered from 0. filter[execution] is optional and defaults to 0, which is the only execution a job with the default parallelism of 1 has.
Parameters
id uuid, required - The id.
filter[execution] int
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.
Parallel executions are numbered from 0. filter[execution] is optional and defaults to 0, which is the only execution a job with the default parallelism of 1 has.
Parameters
id uuid, required - The id.
filter[execution] int
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/test-atoms
Returns a job's test atoms as JSON Lines.
EXPERIMENTAL — This endpoint is experimental and may change without notice. Field names and response shapes are not yet stable. Do not depend on this endpoint in production clients.
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/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 - Maximum items in one page. Out-of-range values are rejected with 400 rather than clamped. The maximum is 50.
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.
GET /api/v3/orgs/:id/sso-group-mappings
Returns an organization's SSO group mappings.
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.
PUT /api/v3/orgs/:id/sso-group-mappings
Replaces an organization's SSO group mappings, returning the new state.
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
204 No Content
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.
At least one of filter[slug] (resolving a single project), filter[org_id] (listing an org's projects), or filter[following] (listing projects followed by the authenticated user) must be provided. If filter[slug] is provided then it must be the only filter. Both filter[org_id] and filter[following] can be used by themselves or together.
filter[name] is optional and narrows the org's projects by a case-insensitive name search. It can be used with both filter[org_id] and filter[following] but combining it with filter[slug] is a 400.
If filter[following] is provided, it may only be given the value "true". Anything else will result in a 400. Filtering for projects which are not followed is not supported.
order_by chooses the order the projects come back in. It may be given "name", which orders them alphabetically, or "last_active_at", which orders them by how recently they last built. Any other value is a 400. An omitted order_by is "name". A single project resolved by filter[slug] has no order to it, so order_by is accepted and ignored there.
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.
The is_followed attribute reports whether the authenticated caller follows the project. It is returned however the projects were selected, so a listing that did not filter on filter[following] carries a mix of true and false.
Notes on pagination:
Parameters
filter[following] string
filter[name] string
filter[org_id] uuid
filter[slug] string
order_by string
page[cursor] string
page[limit] int - Maximum items in one page. Out-of-range values are rejected with 400 rather than clamped. The maximum is 50.
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.
The is_followed attribute reports whether the authenticated caller follows 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 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 - Maximum items in one page. Out-of-range values are rejected with 400 rather than clamped. The maximum is 100.
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 - Maximum items in one page. Out-of-range values are rejected with 400 rather than clamped. The maximum is 100.
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 matching the request's single filter parameter.
Parameters
filter[namespace] string, required
filter[org_id] uuid, required
filter[resource_class] string, required
page[cursor] string
page[limit] int
Responses
200 OK
400 A filter parameter is required.
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 runner resource classes filtered by org or slug.
Exactly one of filter[org_id] (all classes in an org) or filter[slug] (a single class by namespace/name) is required.
Parameters
filter[org_id] uuid
filter[slug] string
Responses
200 OK
400 Provide filter[org_id] or filter[slug], not both.
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.
Either filter[project_id] or filter[user_id]=me is required. filter[project_id] returns the runs for a single project; filter[user_id]=me returns the caller's own recent runs across projects.
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.
The optional order_by_workflows field sorts nested workflows when include requests them. It accepts "created asc" or "created desc" (default created desc / newest first). With the truncation cap, "created asc" returns the oldest workflows. Invalid values return 400 even when include is omitted.
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). Only scheduled triggers may carry parameters; supplying them for any other event type is a 400.
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
204 No Content
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. parameters replaces a scheduled trigger's pipeline parameters wholesale — omitted leaves them unchanged, an empty object clears them — and is a 400 for any other provider.
Authenticated identities (human or machine). Use ?filter[user_id]=me to resolve the authenticated identity.
GET /api/v3/users
Returns a list of users limited by filter query parameters.
Only filter[user_id]=me is supported currently - returning a single-element collection for the authenticated identity.
Parameters
filter[user_id] string, 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.
Workflows
Workflows organise jobs into a dependency graph. A run may produce multiple workflows that execute in parallel or sequence.
GET /api/v3/workflows
Lists the workflows in a run.
List the workflows in a run. Filter by the required filter[run_id]. The optional order_by query parameter accepts "created asc" or "created desc" (default created desc / newest first).
Parameters
filter[run_id] uuid, required
order_by 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 Not Found
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
GET /api/v3/workflows/:id
Retrieve a single workflow 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 workflows does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/workflows/:id/cancel
Requests cancellation of a workflow.
Cancellation is processed asynchronously, so the endpoint returns 202 Accepted with the workflow's id rather than a representation of its final state.
Parameters
id uuid, required - The id.
Responses
202 Accepted
400 Bad Request
401 Provide a valid Authorization header.
403 You do not have access to this resource.
404 The requested workflows does not exist.
429 Too many requests. See Retry-After header.
500 An unexpected error occurred.
POST /api/v3/workflows/:id/rerun
Reruns an existing workflow, creating and returning a new workflow.
By default every job is rerun; set is_from_failed to rerun only the failed jobs and their dependents. The source workflow is not modified.
