> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usepatchwork.co/llms.txt
> Use this file to discover all available pages before exploring further.

# The Confirmation object

> A write held at an approval gate, and the decision that releases it.

A patch wired with **Always ask** does not execute when the agent calls it. The call is recorded, the run pauses in `awaiting_input`, and it waits for a human decision.

See [Confirmations](/guides/confirmations) for the flow.

## Discovering one

`GET /v1/loom/threads` returns `pending_confirmation` on the affected thread:

```json theme={null}
{
  "run_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "tool_call_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "patch_ref": "send_payment@3",
  "summary": { "title": "Send 50 USDC to Jane" },
  "risk": "high"
}
```

<ResponseField name="run_id" type="uuid" required>
  The paused run.
</ResponseField>

<ResponseField name="tool_call_id" type="uuid" required>
  Pass this to the confirm endpoint.
</ResponseField>

<ResponseField name="patch_ref" type="string" required>
  The patch the agent wants to call.
</ResponseField>

<ResponseField name="summary" type="object">
  A human-readable description of the write, built for your approval prompt. Render this rather than raw `args`.
</ResponseField>

<ResponseField name="risk" type="string">
  Effective risk level. A reasonable input to how prominent the prompt should be.
</ResponseField>

The same payload arrives as the `write.confirmation_requested` [event](/api-reference/event) if you use realtime.

## Deciding

`POST /v1/loom/runs/{run_id}/confirm`

```json theme={null}
{ "tool_call_id": "9b1deb4d-…", "decision": "approve" }
```

<ParamField body="tool_call_id" type="uuid" required>
  The held call.
</ParamField>

<ParamField body="decision" type="enum" required>
  `approve` or `reject`.
</ParamField>

<ParamField body="detail" type="object">
  Optional. Recorded on the tool call and passed to the model — a short reason on a rejection produces a better next turn.
</ParamField>

Returns `202`. On approve, Patchwork performs the write server-side and resumes the run; on reject, the model is told it was declined and the run resumes anyway.

<Warning>
  A `202` means the decision was accepted, not that the write succeeded. If an approved write fails, the run continues so the agent can explain, and the tool call is recorded as `failed`. Check the run or the trace.
</Warning>

## Errors

| Code | Status | When |
| - | - | - |
| `unknown_confirmation` | `404` | No pending gated call with that id, or already resolved. |
| `not_awaiting_confirmation` | `422` | The run is not paused at a gate. |
| `invalid_decision` | `422` | Not `approve` or `reject`. |
| `awaiting_confirmation` | `422` | You posted a message instead of deciding. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.