Reviews

Create a review

Agents submit a review request tied to a template. The response is returned immediately — the decision (if any) is delivered via callback_url webhook or retrieved by polling GET /reviews/:id.

If the template has auto_approve=true, the review is created and decided in one step; the response includes decision: "approved" and the callback fires immediately.

post/api/v1/reviews

Request

  • Base URL: https://api.gatewerk.com
  • URL: https://api.gatewerk.com/api/v1/reviews
  • Auth: HTTP bearer

Request body

templatestring required

Template slug.

payloadJsonObject required

Free-form JSON object.

callback_urlstring uri

HTTPS URL to receive decision webhooks. Validated against SSRF rules (no private IPs). Omit to poll instead.

priority'low' | 'normal' | 'high' | 'critical'
actionsstring[]
confidencenumber
irreversibility'reversible' | 'costly_reversible' | 'irreversible'
assigneestring
metadataJsonObject

Free-form JSON object.

oversight'blocking' | 'monitoring'

Oversight mode for the review. 'blocking' (default) pauses the agent until a human decides. 'monitoring' records the action and auto-confirms after the veto window; the human can veto before the window closes.

idempotency_keystring

Client-supplied deduplication key. A second POST with the same (project, idempotency_key) pair returns the existing review instead of creating a duplicate. Terminal conflict (decided/expired review) returns 409 idempotency_key_terminal_conflict.

trace_urlstring

Optional deep link to the originating agent trace. Must be https.

max_iterationsinteger

Per-review cap on revision rounds. Overrides the template-level default. Worker auto-closes awaiting_iteration reviews whose current_version - 1 >= max_iterations.

Response

Review created (or auto-approved).

object'review' required
idstring required
project_idstring required
template_idstring nullable
template_slugstring required
payloadJsonObject required

Free-form JSON object.

suggested_valueJsonObject

Free-form JSON object.

approved_valueJsonObject

Free-form JSON object.

edited_payloadJsonObject

Free-form JSON object.

callback_urlstring nullable
priority'low' | 'normal' | 'high' | 'critical' required
status'pending' | 'awaiting_iteration' | 'decided' | 'expired' | 'archived' required

Canonical review status. Wire-format output is always one of these five values. Query-param status filter additionally accepts the legacy 'changes_requested' alias as a deprecated input for one minor version per spec §11.3 — removed in v2.0.

decision'approved' | 'rejected' | 'edited' | 'retried' | 'expired'
feedbackstring nullable
decided_bystring nullable
decided_by_verifiedboolean nullable

Whether decided_by names a confirmed identity. False only for a decision made through a PUBLIC review link, where the decider is the recipient_label the sharer typed and nothing verified it. Null for reviews decided before this field existed: render no claim rather than assuming unverified.

decided_atstring date-time nullable
current_versioninteger required
assigneestring nullable
metadataJsonObject

Free-form JSON object.

action_valuestring nullable
action_labelstring nullable
created_atstring date-time required
updated_atstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.