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

# Reviews

> Record a person's approve, reject or edit of agent work given outside the approval box.

A review is a person's verdict on something an agent made, given wherever that work is reviewed —
an app's publishing queue, a caption edited before it goes out. Decisions made in a session's
approval box are recorded on their own (`tool.confirm.resolved`); a review is the same judgement from
anywhere else.

## Create a review

`POST /v1/reviews` — scope `sessions:write`

```json theme={"system"}
{
  "decision": "edit",
  "reason": "the hook is too slow",
  "file_ids": ["fil_01H9AB..."],
  "subject": { "app_post_id": "post_42" },
  "before": { "caption": "Watch this", "title": "Clip 1" },
  "after": { "caption": "You won't guess the ending", "title": "Clip 1" }
}
```

| Field              |          |                                                                  |
| ------------------ | -------- | ---------------------------------------------------------------- |
| `decision`         | required | `approve`, `reject` or `edit`.                                   |
| `reason`           | optional | Why, in the reviewer's words; `null` when none was given.        |
| `file_ids`         | optional | The files under review (`fil_…`, at most 50).                    |
| `session_id`       | optional | The session whose work this is, when no file names it.           |
| `subject`          | optional | What was reviewed, in your own terms.                            |
| `before` / `after` | optional | The fields as the agent left them and as the reviewer left them. |

→ `201 Created`

```json theme={"system"}
{ "id": "rev_01H9AB...", "object": "review", "session_id": "ses_01H9AB...", "board_card_id": "crd_01H9AB..." }
```

The actor is the credential that called — never a body field. `session_id` is the one you named,
else the session that produced the first named file; `board_card_id` is the board card that session
was working. An id that does not belong to your organization links to nothing (`null`).