Fetch a correction with its copies

GET

/v1/corrections/{correctionId}

const url = 'https://example.com/v1/corrections/example';
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/example \
  --header 'Authorization: Bearer <token>'

Returns the correction (live or not) with the stored copy of the run’s input and output.

Authorizations

bearerAuth

Parameters

Path Parameters

correctionId

required

string

>= 1 characters

Correction id.

Responses

200

Correction with copies.

application/json

A correction with the stored copies of what was corrected.

object

required

string

tenantId

required

string

projectId

required

string

runId

required

string

subject

required

What a corrected run ran: an agent at a version, or a flow at a version.

object

kind

required

string

Allowed values: agent flow

required

string

version

required

string

decisions

Whether the run’s decisions were right. Absent when it says nothing about them.

string

Allowed values: right wrong

shouldCall

With decisions: "wrong": the calls the agent should have made.

Array<object>

object

tool

required

string

>= 1 characters <= 200 characters

args

required

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

<= 100 properties

mustNotCall

With decisions: "wrong": the tools that should not have been called.

Array<string>

answer

Whether the run’s answer was right. Absent when it says nothing about it.

string

Allowed values: right wrong

shouldSay

With answer: "wrong": what it should have said.

string

why

string

items

For an answer that is a ranked list: each item, and whether it was right there.

Array<object>

object

key

required

The caller’s stable id for the item, such as a matched case’s id, never the item’s own text.

string

>= 1 characters

pointer

Where the item is in the run’s output, as a JSON Pointer (RFC 6901), e.g. /matches/2.

string

rank

The item’s position in the ranked list (0 = first).

integer

verdict

required

string

Allowed values: right wrong

correctorGroupId

The corrector group the correction is recorded under. Absent when unclassified (counts with weight 1).

string

expert

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.

boolean

madeBy

required

Who asserted a correction: the authenticated caller, never a typed name.

object

kind

required

string

Allowed values: user service

required

A user id, or for a service token its token or session id.

string

participantId

The app’s opaque id for its end user who corrected it, when an app corrected it on their behalf.

string

status

required

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.

string

Allowed values: open being-fixed with-owner fixed wont-fix removed

sortedTo

Who works on it: Improve, a developer, or the agent’s owner. Absent while unsorted.

string

Allowed values: improve developer owner

sorted

object

required

One of:

object
object

object

kind

required

string

Allowed values: fix-job rule

reason

string

required

string format: date-time

link

One of:

object
object

object

kind

required

string

Allowed values: improve-run suggested-change

required

The Improve run’s or suggested change’s id, without its prefix.

string

fixedIn

Present while it’s fixed, and beside reopenedIn after a test run reopened it.

object

version

The version that fixed it. Absent for recorded-right, which nothing had to fix.

string

how

required

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.

string

Allowed values: pin latest recorded-right

Who asserted a correction: the authenticated caller, never a typed name.

object

kind

required

string

Allowed values: user service

required

A user id, or for a service token its token or session id.

string

required

string format: date-time

reopenedIn

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

version

required

The version that gets it wrong.

string

how

required

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.

string

Allowed values: pin went-back unpin latest

Who pinned, went back or unpinned. Absent when Latest moved.

object

kind

required

string

Allowed values: user service

required

A user id, or for a service token its token or session id.

string

required

string format: date-time

statusNote

object

text

required

string

required

Who asserted a correction: the authenticated caller, never a typed name.

object

kind

required

string

Allowed values: user service

required

A user id, or for a service token its token or session id.

string

required

string format: date-time

createdAt

required

string format: date-time

updatedAt

required

When it last changed: createdAt until something changes it.

string format: date-time

unregisteredAt

Set when the correction was removed or superseded.

string format: date-time

supersededBy

The correction that replaced this one.

string

run

required

The stored copy of a corrected run’s input and output, taken when it was first corrected.

object

runId

required

string

subject

required

What a corrected run ran: an agent at a version, or a flow at a version.

object

kind

required

string

Allowed values: agent flow

required

string

version

required

string

input

required

context

What a corrected run needs besides its input to be replayed, captured when it was first corrected. For an agent turn: the conversation before it, what its retrievals returned, and the decision at its session approval gate. For a flow run: its tool calls with their results. For both: the env values its tools were sent.

object

history

The conversation’s messages before the turn, oldest first (at most the last 200).

Array

historyTruncated

Whether older messages were left out of history.

boolean

retrieved

What the turn’s retrievals returned.

recalled

Messages of earlier conversations the turn recalled (intents over conversations), as quoted to the model.

sessionApproval

The reviewer’s decision at the turn’s session approval gate, when the turn waited on one. A replay of the turn follows it.

object

approved

required

boolean

rationale

The reviewer’s reason for a rejection.

string

flow

For a flow run: what it did, kept at its first correction so it can be replayed. Every tool call it made with its result (at its tool nodes, in its agent steps’ turns and in its sub-flows), at most 500, and its agent steps.

object

calls

required

Array<object>

object

runId

required

The run that made it: the flow run, a sub-flow’s, or an agent step’s turn.

string

nodeId

The tool node that made it, or the agent step whose turn did.

string

scope

The loop iteration, in a loop body.

string

toolId

required

string

arguments

result

fromEvent

An agent step’s turn kept the result as outside data: another system’s answer to a paused call, or a result its tool says is outside data. A replay hands it to the model as data, as the turn did. Absent for a tool node’s call, and for a run corrected before the mark was kept.

boolean

steps

required

Array<object>

object

runId

required

string

nodeId

string

scope

string

agentId

required

string

agentVersion

required

string

retrieved

What the step’s turn retrieved.

recalled

Messages of earlier conversations the step’s turn recalled.

truncated

More calls were made than were kept.

boolean

toolEnv

The env values each tool’s calls were sent (needsSpec.env), by tool id: its first call’s, as the run recorded them. A replay sends them to a read-only tool it runs live, so the tool reads the config the run saw, not today’s. Absent for a run from before env was recorded.

object

key

additional properties

object

key

additional properties

string

replayOf

When the corrected run is a comparison’s replay: the run it re-ran, stamped at its first correction. A test set built from corrections leaves replays out.

string

output

required

segments

The segment path the run was started with (empty: none). Absent for runs corrected before it was recorded.

Array<object>

object

key

required

Lowercase, like an identifier: company, contact-role.

string

/^[a-z][a-z0-9_-]{0,63}$/

value

required

string

>= 1 characters <= 256 characters

capturedAt

required

string format: date-time

Example

{
  "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"
    }
  },
  "run": {
    "subject": {
      "kind": "agent"
    },
    "context": {
      "flow": {
        "calls": [
          {
            "fromEvent": true
          }
        ]
      }
    }
  }
}

401

Missing / malformed / expired / revoked bearer token.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

No correction with that id under this tenant.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

503

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

Fetch a correction with its copies

Authorizations

Parameters

Path Parameters

Responses

200

Example

401

Examplegenerated

404

Examplegenerated

503

Examplegenerated

See also

Example^generated

Example^generated

Example^generated