# Re-sort a correction or change its status

PATCH

/v1/corrections/{correctionId}

```sh
curl --request PATCH \
  --url https://example.com/v1/corrections/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "sortedTo": "improve", "status": "open", "link": "example", "reason": "example" }'
```

A re-sort, a status, or both (the re-sort first), by the change table: re-sorting from `open`, `being-fixed` or `with-owner` (to `owner` sets `with-owner`; away from `owner`, `open`); `being-fixed` from `open` or `with-owner`, with `link`; `open` from `being-fixed` or `wont-fix` (`with-owner` for one sorted to the owner); `wont-fix` from anything but `removed`, with `reason`, and it drops `fixedIn`. `fixed` is set only by a pin or a deploy. Anything else is `409 correction-status-change-not-allowed`. Needs `publish` on the correction’s agent (or flow), or, for one more than one project serves, `write` on the correction’s project.

## Authorizations

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

## Parameters

### Path Parameters

**correctionId**

required

string

\>= 1 characters

Correction id.

### Header Parameters

**Idempotency-Key**

string

\>= 1 characters

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

application/json

A re-sort, a status, or both (the re-sort first). `fixed` is set only by a pin or a deploy, and `removed` by `POST /v1/corrections/{correctionId}/remove`.

object

\>= 1 properties

**sortedTo**

From `open`, `being-fixed` or `with-owner`. To `owner` sets `with-owner`; away from `owner`, `open`.

string

Allowed values: improve developer owner

**status**

`being-fixed` from `open` or `with-owner`, with `link`. `open` from `being-fixed` or `wont-fix`. `wont-fix` from anything but `removed`, with `reason`.

string

Allowed values: open being-fixed wont-fix

**link**

With `status: "being-fixed"`: a pull request URL, an Improve run (`ir-<its id>`) or a suggested change (`sc-<its id>`).

string

**reason**

Required for `wont-fix`; with `open`, why it went back. Otherwise the re-sort’s reason.

string

\>= 1 characters <= 4000 characters

## Responses

### 200

The changed correction.

application/json

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

##### Example

```json
{
  "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 body: a link without `being-fixed`, `being-fixed` without a link, or `wont-fix` without a reason.

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"
  }
}
```

### 403

`permission-denied`: this needs publish on the agent, or write on the correction’s project for an agent more than one project serves.

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"
  }
}
```

### 404

No live 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

##### Examplegenerated

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

### 409

`correction-status-change-not-allowed`: the change table does not allow it from its status, or it changed twice while the change was made: read it and try again (`details: { from, to }`).

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"
  }
}
```

### 413

The request body is over the API’s limit (`request-too-large`; `details.maxBytes` says how much).

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"
  }
}
```

### 500

Server error (unmapped domain code or framework crash).

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

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

- [`GET /v1/corrections/{correctionId}`: Fetch a correction with its copies](https://docs.kindgi.com/v0.4.0/reference/api/operations/correctionsget.md)
- [`POST /v1/corrections/{correctionId}/remove`: Remove a correction](https://docs.kindgi.com/v0.4.0/reference/api/operations/correctionsremove.md)
- [Kindgi 0.4.0](https://docs.kindgi.com/v0.4.0/releases/0.4.0.md)
- [Error code `correction-status-change-not-allowed`](https://docs.kindgi.com/v0.4.0/reference/errors.md#correction-status-change-not-allowed)
- [Error code `idempotency-store-unavailable`](https://docs.kindgi.com/v0.4.0/reference/errors.md#idempotency-store-unavailable)
- [Error code `permission-denied`](https://docs.kindgi.com/v0.4.0/reference/errors.md#permission-denied)
- [Error code `request-too-large`](https://docs.kindgi.com/v0.4.0/reference/errors.md#request-too-large)
- [Every error code](https://docs.kindgi.com/v0.4.0/reference/errors.md)