# Send a decision to the hosted review queue

`POST /api/v1/decisions/{decisionId}/review` · operationId `requestDecisionReview`

For developers: your server sends this request with a server key; it is not a button in the dashboard. To see the same information without code, open **Control › Approvals › Waiting** in the dashboard.

Use when your own policy holds an action that Telltale allowed. It only tightens: a denied decision cannot be reviewed (409). The body is an empty object {}.

## Authentication

Send `Authorization: Bearer YOUR_SERVER_KEY` (siteServerKey: Site server key in Authorization: Bearer <key> (the scheme is case-insensitive and required; a bare key is 401). Shown once on creation or rotation. Publishable keys cannot authenticate). Keep the server key in server-only configuration; never send it to a browser.

## Parameters

- `decisionId` (path, string, required)

## Request body

Content-Type: application/json (required)


```json
{}
```

## Responses

- **200**: Success · body `Decision`
- **400**: bad_request: the request is invalid; message says what to fix and field names the request field · body `Error`
- **401**: unauthorized (missing or invalid server key, missing Bearer scheme) · body `Error`
- **403**: forbidden: the call came from a browser page or another Site; call from your server with this Site’s server key · body `Error`
- **404**: not_found: unknown path, or an ID in the path that is not on this Site · body `Error`
- **409**: conflict: the decision was denied, or is already in review · body `Error`
- **413**: payload_too_large: the request body exceeds 131072 bytes · body `Error`
- **429**: rate_limited: wait for Retry-After · body `Error` · headers `Retry-After`
- **500**: internal_error: fail the protected action; do not retry automatically · body `Error`
- **503**: service_unavailable: temporarily unavailable; only verify retries · body `Error`

### Success body fields

- `decisionId` (string, required)
- `actionId` (string, required) · pattern `^[A-Za-z0-9_-]{1,64}$`
- `sessionId` (string, required)
- `targetId` (string | null, optional)
- `decision` ("allow" | "review" | "deny", required)
- `purpose` ("protect" | "display", required)
- `verdict` ("human" | "agent" | "unknown", required)
- `agentEvidence` ("verified" | "automation-trace" | "injected-input" | "sustained-behaviour" | "behaviour-change" | "behaviour-corroborated" | "cursor-driven" | "behaviour" | null, optional)
- `heldInsteadOfDeny` (true, optional)
- `confidence` ("high" | "medium" | "low" | null, optional)
- `behaviourOnlyDenyEnabled` (boolean, optional)
- `behaviourOnlyReason` (string | null, optional)
- `stepUp` (StepUpHint | null, optional)
- `stepUp.reason` ("behaviour_only_agent" | "edge_evidence" | "policy" | "backend", required): behaviour_only_agent: the AI agent rule said Deny but the verdict rests on behaviour alone. edge_evidence: evidence your edge reported raised the decision to review. policy: the rule says Hold for review. backend: your backend sent the check to review.
- `stepUp.expiresAt` (number, required): The step-up result must arrive before this (15 minutes after the hold).
- `stepUp.report` (string, required): Where to POST the step-up result.
- `created` (number, required): Unix epoch milliseconds.
- `outcome` (object | null, optional)
- `outcome.outcome` ("performed" | "blocked" | "failed", required)
- `outcome.reason` (string | null, required)
- `outcome.at` (number, required): Unix epoch milliseconds.
- `review` (object | null, optional)
- `review.status` ("pending" | "approved" | "rejected" | "cancelled", required)
- `review.resolvedAt` (integer | null, required)
- `review.expiresAt` (integer | null, required)
- `review.redeemedAt` (integer | null, required)
- `review.via` ("step-up", optional): Present when your step-up report settled it.
- `review.method` (string, optional)
- `approvalToken` (string, optional): Present only while an approval can still be redeemed (approved, unexpired, unused). An approval is evidence, not authorization.

Failures are not verdicts. Error bodies follow the `Error` schema: `code` is one of `bad_request`, `unauthorized`, `session_reinit_required`, `forbidden`, `not_found`, `conflict`, `identity_required`, `payload_too_large`, `rate_limited`, `internal_error`, `service_unavailable`, `request_failed`, `approval_invalid`, `approval_used`, `approval_expired`, `approval_mismatch`, `step_up_not_held`, `step_up_mismatch`, `step_up_settled`, `step_up_expired`, `step_up_superseded`, `agent_tokens_disabled`, `tool_not_approved`, `tool_not_read_only`. [Errors and retries](/docs/errors) explains each code and what to do.

## Example

```sh tab=curl
curl -sS -X POST 'https://app.trytelltale.dev/api/v1/decisions/decision_PASTE_DECISION_ID/review' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  --data '{}'
```

```js tab=fetch
const response = await fetch("https://app.trytelltale.dev/api/v1/decisions/decision_PASTE_DECISION_ID/review", {
  method: "POST",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({}),
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();
```

Machine-readable contract: [openapi.json](https://app.trytelltale.dev/openapi.json). Request builder: the [API explorer](/docs/api-explorer) shows every operation as curl; it sends requests only on a local dashboard.