# Record a decision

> Record a decision on a pull request: why the change is made the way it is (proposal), something you say is true of it (claim), what you changed to fix a failure (fix), or a note.

<div class="g1t-endpoint"><span class="g1t-method" data-method="post">POST</span><code>/repos/{owner}/{name}/pulls/{number}/decisions</code></div>

It is kept with confidence claimed, attributed to you, with the issue the pull request is for, and published as decision.recorded. evidence is an object of what it rests on, such as {"commit": "…", "check": "CI"}; session_id names the session it was made in. g1t records the decisions it saw proved itself: integration_failure and integration_passed when the merge queue combines pull requests (confidence tested), approval when a person approves (approved), and merge.

Kept as `claimed`. g1t records `integration_failure`, `integration_passed`, `approval` and `merge` itself. Publishes `decision.recorded`. See [decision records](/guides/why-blame/#decision-records).

- **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`.
- **MCP tool:** [`pull_request`](/reference/mcp/#pull_request) with `action` `record_decision`, and the same inputs
- **Scope:** An access token needs [`pull_requests:write`](/guides/authentication/#scopes).

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | Yes | The workspace that owns the repository. |
| `name` | string | Yes | The repository's name. |
| `number` | integer | Yes | The number shown after the #. Issues and pull requests share one sequence. |

## Body parameters

Send a JSON object. Names are `snake_case`, as in responses; the `camelCase` spelling is accepted too.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | Yes | What it is: why the change is made this way (proposal), something true of it (claim), what fixed a failure (fix), or a note. One of `proposal`, `claim`, `fix`, `note`. |
| `summary` | string | Yes | The decision, in a sentence or two. At most 2,000 characters. |
| `evidence` | object | No | What it rests on, such as a commit, a check's name or the pull requests involved. At most 8 KB of JSON. |
| `session_id` | string | No | The session it was made in, if you have one. |

## Example request

```sh
curl -X POST https://api.g1t.sh/repos/flagon-io/hello/pulls/14/decisions \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "fix",
    "summary": "Renamed the config key #12 also introduced, so both read retry_limit.",
    "evidence": {
      "commit": "7d3e9a1c5b2f4e6a8c0d2e4f6a8b0c2d4e6f8a0b"
    },
    "session_id": "ses_01kpz7x9y1z3a5b7c9d1e3f5gh"
  }'
```

## Example response

A successful request answers `200` with:

```json
{
  "id": "dec_01kpz9a1b3c5d7e9f1g3h5j7kb",
  "issue": 9,
  "pull": 14,
  "session_id": "ses_01kpz7x9y1z3a5b7c9d1e3f5gh",
  "actor": "ana",
  "kind": "fix",
  "confidence": "claimed",
  "summary": "Renamed the config key #12 also introduced, so both read retry_limit.",
  "evidence": {
    "commit": "7d3e9a1c5b2f4e6a8c0d2e4f6a8b0c2d4e6f8a0b"
  },
  "created_at": "2026-10-12T15:31:40.019Z"
}
```

## Errors

A failed request answers with one of these statuses and a body like `{"error": {"code": "not_found", "message": "Repository not found."}}`. See [errors](/reference/api/#errors).

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthenticated` | A token is required, or the one sent is not valid. |
| 403 | `forbidden` | The token is valid but not allowed to do this, such as a member-only change, or a token without the scope it needs. |
| 404 | `not_found` | It does not exist, or you cannot see it. |
| 409 | `conflict` | The request conflicts with the current state. |
| 422 | `invalid` | The input is not valid. `message` says which field and why. |