# List corrections

GET

/v1/corrections

```sh
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

- **[bearerAuth](https://docs.kindgi.com/v0.5.0/reference/api.md#bearerauth)**

## Parameters

### Query Parameters

**limit**

integer

default: 25 >= 1 <= 100

1..100. Default 25.

**cursor**

string

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.

**runId**

string

\>= 1 characters

Only corrections of this run.

**agentId**

string

\>= 1 characters

Only corrections of runs of this agent.

**agentVersion**

string

\>= 1 characters

Only corrections of runs of this agent version. Needs `agentId`.

**flowId**

string

\>= 1 characters

Only corrections of runs of this flow.

**status**

Array\<string>

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

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.

**sortedTo**

Array\<string>

Allowed values: none improve developer owner

Only corrections sorted to these (repeated or comma-separated), with `none` for unsorted ones.

**from**

string

Allowed values: experts end-users all

`experts`: corrections under a restricted corrector group. `end-users`: an app’s end users’ (`participantId`), not experts’. `all` (the default): every one.

**madeBy**

string

Allowed values: me

`me`: only the caller’s own corrections.

**since**

string format: date-time

Only corrections made at or after this time.

**until**

string format: date-time

Only corrections made before this time.

**correctorGroupId**

string

\>= 1 characters

Only corrections recorded under this corrector group.

**participantId**

string

\>= 1 characters

Only corrections made for this app end user’s opaque id.

**scopeKind**

Discriminator for the ?scopeKind + ?scopeId + ?inherit triplet. Tenant carries no id (implicit from session); org/project require scopeId.

string

Allowed values: tenant org project

Optional scope discriminator. If absent, no scope filter is applied.

**scopeId**

string

\>= 1 characters

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

### 200

Page of corrections.

application/json

object

**data**

required

Array\<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

**id**

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

**id**

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

**id**

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

**by**

required

One of:

- **object**

  object

  **kind**

  required

  string

  Allowed values: fix-job rule

- **object**

  object

  **kind**

  required

  string

  Allowed values: user service

  **id**

  required

  string

**reason**

string

**at**

required

string format: date-time

**link**

One of:

- **object**

  object

  **kind**

  required

  string

  Allowed values: improve-run suggested-change

  **id**

  required

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

  string

- **object**

  object

  **kind**

  required

  string

  Allowed values: pull-request

  **url**

  required

  string format: uri

**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

**by**

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

object

**kind**

required

string

Allowed values: user service

**id**

required

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

string

**at**

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

**by**

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

object

**kind**

required

string

Allowed values: user service

**id**

required

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

string

**at**

required

string format: date-time

**statusNote**

object

**text**

required

string

**by**

required

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

object

**kind**

required

string

Allowed values: user service

**id**

required

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

string

**at**

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

**nextCursor**

Opaque cursor. Treat as opaque on the client.

string

**hasMore**

required

boolean

##### Example

```json
{
  "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"
        }
      }
    }
  ]
}
```

### 400

Malformed query parameter.

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

##### Examplegenerated

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

### 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

##### Examplegenerated

```json
{
  "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

##### Examplegenerated

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

## See also

- [`POST /v1/corrections`: Correct a run](https://docs.kindgi.com/v0.5.0/reference/api/operations/correctionscreate.md)
- [Corrections reference](https://docs.kindgi.com/v0.5.0/guides/improve/expert-queue-reference.md)
- [Kindgi 0.4.0](https://docs.kindgi.com/v0.5.0/releases/0.4.0.md)
- [Error code `database-busy`](https://docs.kindgi.com/v0.5.0/reference/errors.md#database-busy)
- [Every error code](https://docs.kindgi.com/v0.5.0/reference/errors.md)