---
title: "Record a review decision"
method: POST
path: "/api/v1/production-review/submissions/{submissionRef}/decisions"
tags: ["Production Review"]
---

# Record a review decision

`POST /api/v1/production-review/submissions/{submissionRef}/decisions`

## Request

- Base URL: `https://numonic.ai`
- URL: `https://numonic.ai/api/v1/production-review/submissions/{submissionRef}/decisions`
- Auth: API key in header `x-api-key`

Appends `needs_changes` or `approved`; the latest decision is the state. Session authentication only in v1: API-key principals receive 403.

## Path parameters

- `submissionRef` string, required: URL-encoded submission reference `native:<40-hex>` (EntityRef wire form)

## Headers

- `Idempotency-Key` string, required: Client-generated key (e.g. a UUID). Replaying the same key returns the original result; reusing it with a different payload is 409.

## Request body

- object
  - `outcome` 'needs_changes' | 'approved', required

## Response `201`

The submission after the decision

- ReviewSubmission: `state` is derived: the latest decision outcome, else `pending`. A resubmission is a new submission with `supersedes` and the next `versionNumber`.
  - `ref` string, required
  - `projectRef` string, required
  - `workItemRef` string
  - `title` string, required
  - `media` object, required
    - `versionNumber` integer, required
    - `media` object, required
      - `kind` 'numonic-asset', required
      - `assetH` string, required
    - `numonicAssetH` string
  - `state` 'pending' | 'needs_changes' | 'approved', required
  - `submittedBy` object, required
    - `displayName` string, required
    - `numonicAgentId` string
  - `submittedAt` string, required
  - `supersedes` string
  - `decisions` object[], required
    - `outcome` 'needs_changes' | 'approved', required
    - `decidedBy` object, required
      - `displayName` string, required
      - `numonicAgentId` string
    - `decidedAt` string, required
  - `externalRefs` unknown[], required
    - unknown

## Other responses

- `400`: Validation failed or Idempotency-Key missing
- `401`: Unauthorized
- `403`: Insufficient scope or role
- `404`: Not found in this tenant
- `409`: Idempotency-Key reused with a different payload

---

[API](https://skmtc.dev/numonic/apis/numonic-api.md) · [All operations](https://skmtc.dev/numonic/apis/numonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numonic/apis/numonic-api/revisions/6c559bef1e35?raw)