List corrections
const url = 'https://example.com/v1/corrections?limit=25&from=experts&madeBy=me&scopeKind=tenant';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://example.com/v1/corrections?limit=25&from=experts&madeBy=me&scopeKind=tenant' \ --header 'Authorization: Bearer <token>'Corrections (not superseded, and not removed unless status asks for removed), newest first, cursor-paginated. Filter by run, agent (and version), flow, status, sorting, who made them, when, corrector group or participant; ?scopeKind + ?scopeId narrow to a project. Each one comes back only when the caller may read its project.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”1..100. Default 25.
Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.
Only corrections of this run.
Only corrections of runs of this agent.
Only corrections of runs of this agent version. Needs agentId.
Only corrections of runs of this flow.
Only corrections in these statuses: one, or several, repeated or comma-separated. not-fixed is short for open, being-fixed and with-owner. Removed corrections come back only when removed is asked for.
Only corrections sorted to these (repeated or comma-separated), with none for unsorted ones.
experts: corrections under a restricted corrector group. end-users: an app’s end users’ (participantId), not experts’. all (the default): every one.
me: only the caller’s own corrections.
Only corrections made at or after this time.
Only corrections made before this time.
Only corrections recorded under this corrector group.
Only corrections made for this app end user’s opaque id.
Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.
Optional scope discriminator. If absent, no scope filter is applied.
Required IF scopeKind is org or project. MUST be absent if scopeKind=tenant (the workspace is implicit from the session). Malformed combinations return 400 scope-invalid.
Responses
Section titled “Responses”Page of corrections.
object
A person’s correction of one run: whether its decisions (the tool calls) and its answer were right, and what was right instead. It says at least one of decisions, answer and items.
object
What a corrected run ran: an agent at a version, or a flow at a version.
object
Whether the run’s decisions were right. Absent when it says nothing about them.
With decisions: "wrong": the calls the agent should have made.
object
The partial set of top-level argument fields to compare, by value. Fields left out are not compared; an empty object asks only that the tool was called. At most 4000 characters in canonical JSON.
object
With decisions: "wrong": the tools that should not have been called.
Whether the run’s answer was right. Absent when it says nothing about it.
With answer: "wrong": what it should have said.
For an answer that is a ranked list: each item, and whether it was right there.
object
The caller’s stable id for the item, such as a matched case’s id, never the item’s own text.
Where the item is in the run’s output, as a JSON Pointer (RFC 6901), e.g. /matches/2.
The item’s position in the ranked list (0 = first).
The corrector group the correction is recorded under. Absent when unclassified (counts with weight 1).
Present (true) when the corrector group was restricted (assertableBy) when the correction was recorded, so whoever recorded it was checked against it. A restriction added or lifted later doesn’t change it.
Who asserted a correction: the authenticated caller, never a typed name.
object
A user id, or for a service token its token or session id.
The app’s opaque id for its end user who corrected it, when an app corrected it on their behalf.
Where it is in being fixed. with-owner while the agent’s owner decides; fixed only when a pin or a deploy fixed it, or it said nothing was wrong; removed can’t come back.
Who works on it: Improve, a developer, or the agent’s owner. Absent while unsorted.
Present while it’s fixed, and beside reopenedIn after a test run reopened it.
object
The version that fixed it. Absent for recorded-right, which nothing had to fix.
pin: a pin fixed it. latest: a deploy or an add moved Latest in a project that follows it. recorded-right: it said nothing was wrong.
Who asserted a correction: the authenticated caller, never a typed name.
object
A user id, or for a service token its token or session id.
Present after a test run got a fixed correction wrong again: it’s open, or with-owner when it’s sorted to the owner, with the fixedIn it had beside it. A status set by hand clears both, and a re-sort alone keeps them. A test run that gets it right again makes it fixed with a new fixedIn.
object
The version that gets it wrong.
How the project came to run it. pin: a pin. went-back: a pin of a version earlier than the one it ran just before. unpin: an unpin. latest: a deploy or an add moved Latest in a project that follows it.
Who pinned, went back or unpinned. Absent when Latest moved.
object
A user id, or for a service token its token or session id.
object
Who asserted a correction: the authenticated caller, never a typed name.
object
A user id, or for a service token its token or session id.
When it last changed: createdAt until something changes it.
Set when the correction was removed or superseded.
The correction that replaced this one.
Opaque cursor. Treat as opaque on the client.
Example
{ "data": [ { "subject": { "kind": "agent" }, "decisions": "right", "answer": "right", "items": [ { "verdict": "right" } ], "expert": true, "madeBy": { "kind": "user" }, "status": "open", "sortedTo": "improve", "sorted": { "by": { "kind": "fix-job" } }, "link": { "kind": "improve-run" }, "fixedIn": { "how": "pin", "by": { "kind": "user" } }, "reopenedIn": { "how": "pin", "by": { "kind": "user" } }, "statusNote": { "by": { "kind": "user" } } } ]}Malformed query parameter.
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" }}The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.
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" }}