Create a queue rule
const url = 'https://example.com/v1/projects/example/queue-rules';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"example","when":{"agentIds":["example"],"flowIds":["example"],"versions":["example"],"status":["completed"],"includeDryRuns":true},"sample":1,"maxOpen":1,"correctorGroupId":"example","enabled":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/projects/example/queue-rules \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "when": { "agentIds": [ "example" ], "flowIds": [ "example" ], "versions": [ "example" ], "status": [ "completed" ], "includeDryRuns": true }, "sample": 1, "maxOpen": 1, "correctorGroupId": "example", "enabled": true }'Version 1 of a rule. From then on, a top-level run of the project that matches when as it ends (and falls in sample, while the rule has fewer than maxOpen open items) is queued for a person’s correction; replays never are. A rule only lists runs: it never starts a model. Needs write on the project.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”ProjectId — opaque branded string.
Header Parameters
Section titled “Header Parameters”Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5). A request whose key store can’t be read before it runs is answered 503 idempotency-store-unavailable with Retry-After: nothing ran, so retry with the same key (from 0.3.0).
Request Bodyrequired
Section titled “Request Bodyrequired”A queue rule as written. It only lists runs: nothing here starts a model.
object
Which of a project’s runs a rule matches as they end. Every field narrows; absent fields don’t. agentIds or flowIds, not both. Top-level runs only (an agent’s own runs, not its turns as a flow’s step); replays never match.
object
These versions exactly, or pinned: runs that got the agent’s pinned version, not one the caller named. Runs from before the runtime recorded how their version was chosen never match pinned.
How the run ended. Only completed today: a correction needs a completed run, so failed and cancelled are refused (400). Absent: completed.
Dry runs are left out unless true.
The share of matching runs queued, decided by the run and rule ids: the same every time and across the rule’s versions, so raising it keeps the runs it took before. Default 1.
Queue nothing while this rule has this many open items. Absent: no cap.
Whose correction it wants: one of this group closes it. Absent: any correction does.
Default true.
Responses
Section titled “Responses”The rule, version 1.
One version of a queue rule; the latest live one applies.
object
Which of a project’s runs a rule matches as they end. Every field narrows; absent fields don’t. agentIds or flowIds, not both. Top-level runs only (an agent’s own runs, not its turns as a flow’s step); replays never match.
object
These versions exactly, or pinned: runs that got the agent’s pinned version, not one the caller named. Runs from before the runtime recorded how their version was chosen never match pinned.
How the run ended. Only completed today: a correction needs a completed run, so failed and cancelled are refused (400). Absent: completed.
Dry runs are left out unless true.
Queue nothing while this rule has this many open items. Absent: no cap.
Whose correction it wants: one of this group closes it. Absent: any correction does.
Who wrote this version.
Example
{ "when": { "status": [ "completed" ] }}Malformed request body.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}No project with that id (project-not-found), or no live corrector group correctorGroupId (corrector-group-not-found).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Idempotency-Key was reused with a different body, or resource-state conflict.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The request body is over the API’s limit (request-too-large; details.maxBytes says how much).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}Server error (unmapped domain code or framework crash).
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The Idempotency-Key store couldn’t be read before the request ran (idempotency-store-unavailable), so nothing was changed; Retry-After (whole seconds) says when to try again with the same key.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}See also
GET /v1/projects/{projectId}/queue-rules: List a project's queue rulesGET /v1/projects/{projectId}: Fetch a project by idPATCH /v1/projects/{projectId}: Partially update a projectDELETE /v1/projects/{projectId}: Delete a project (idempotent)- Error code
corrector-group-not-found - Error code
idempotency-store-unavailable - Error code
project-not-found - Error code
request-too-large - Every error code