---
title: "Create Verification Request"
method: POST
path: "/api/v1/doc-revisions/{revision_id}/verification-requests"
tags: ["authed"]
---

# Create Verification Request

`POST /api/v1/doc-revisions/{revision_id}/verification-requests`

## Request

- Base URL: `https://api.teaflask.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.teaflask.com/api/v1/doc-revisions/{revision_id}/verification-requests`
- Auth: none declared

Creates the request row and starts the suite-authoring workflow.
A request binds to exactly the doc's currently-published revision —
any other revision is refused with the 409, so a stale caller can
never point a suite at content nobody is reading. An organization
with no code to verify against gets the ask recorded born failed as
unverifiable — same policy as the publish hook, with no workspace
burned to discover it mid-flight. A request already in flight on the
revision is answered with a 200 instead of a twin (TEA-1067). If the
orchestration service can't be reached the row is honestly settled as
failed and the caller gets the 503 — never a request that silently goes
nowhere.

## Path parameters

- `revision_id` string, uuid, required

## Response `200`

A request already in flight on this revision is returned

- VerificationRequestResponse
  - `id` string, uuid, required
  - `organization_id` string, uuid, required
  - `doc_revision_id` string, uuid, required
  - `status` 'queued' | 'working' | 'succeeded' | 'failed' | 'unfunded', required: QUEUED and WORKING are workflow-owned; the rest are settled. UNFUNDED is the funding gate's settled state — not FAILED (nothing broke) and not unverifiable (nothing was judged): the organization had no pocket to pay the model, the error column carries the reason sentence, and the resume sweep requeues the row when money lands.
  - `error` string, nullable, required
  - `failure_kind` 'system' | 'doc_contradicted' | 'suite_not_green' | 'unverifiable', required: How machines route a failed request, beside the prose error sentence: system pages a developer, doc_contradicted sends the doc to the drift rewriter, suite_not_green means the authored suite's official run judged against it, unverifiable is the honest no-page no-loop state — a doc with no code to check against or no checkable claims.
  - `requested_by_user_id` string, uuid, nullable, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `201`: Successful Response
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `405`: Method not allowed
- `409`: Revision is not the published one
- `422`: Validation error
- `500`: Internal server error
- `503`: Orchestration unavailable

---

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