---
title: "Create Verification Run"
method: POST
path: "/api/v1/doc-verification-suites/{suite_id}/runs"
tags: ["authed"]
---

# Create Verification Run

`POST /api/v1/doc-verification-suites/{suite_id}/runs`

## 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-verification-suites/{suite_id}/runs`
- Auth: none declared

Creates the run row and starts the run workflow. If the orchestration
service can't be reached the row is honestly settled as an error and the
caller gets the 503 — never a run that silently goes nowhere.

## Path parameters

- `suite_id` string, uuid, required

## Response `201`

Successful Response

- VerificationRunResponse
  - `id` string, uuid, required
  - `organization_id` string, uuid, required
  - `suite_id` string, uuid, required
  - `trigger` 'authoring' | 'drift' | 'drill_repair', required
  - `status` 'running' | 'green' | 'red' | 'error', required
  - `summary` string, nullable, required
  - `repo_shas` object, nullable, required
  - `repo_production_refs` object, nullable, required
  - `library_version` string, nullable, required
  - `started_at` string, date-time, required
  - `finished_at` string, date-time, nullable, required

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `405`: Method not allowed
- `409`: Suite is not runnable
- `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)