API endpoint reference
Operations and schemas generated from the current Verbatik API definition.
Base URL: https://app.verbatik.com/api/v1. Authenticate with a workspace Bearer key.
Open interactive reference · Download OpenAPI 3.1 · Live schema
This checked-in reference is generated from the app API definition. The linked live reference reflects the deployed application. Use the guides for workflow details, including runtime validation and credit behavior.
Operations
| Method | Path | Purpose | Required scope |
|---|---|---|---|
| GET | /models | List available models | models:read |
| POST | /files | Create a presigned media upload | files:write |
| POST | /generations | Create image, video, or audio | generations:write |
| GET | /generations | List API generations | generations:read |
| GET | /generations/{id} | Get generation status and outputs | generations:read |
| POST | /speech | Create multi-block speech | generations:write |
| GET | /speech/{id} | Get multi-block speech status | generations:read |
| GET | /jobs/{id} | Poll any asynchronous job | See guide |
| POST | /agents/runs | Create an Agent production plan | agents:write |
| GET | /agents/runs | List Agent runs | agents:read |
| GET | /agents/runs/{id} | Get an Agent run | agents:read |
| POST | /agents/runs/{id}/approve | Approve an Agent plan | agents:write |
| POST | /agents/runs/{id}/review | Complete the Agent review gate | agents:write |
| POST | /voices | Clone or design a voice | voices:write |
| GET | /voices | List custom voices | voices:read |
| GET | /voices/catalog | List language-specific preset voices | voices:read |
| GET | /voices/{id} | Get a custom voice | voices:read |
| PATCH | /voices/{id} | Rename a custom voice | voices:write |
| DELETE | /voices/{id} | Delete a custom voice | voices:write |
| POST | /personas | Create a reusable visual persona | personas:write |
| GET | /personas | List personas | personas:read |
| GET | /personas/{id} | Get a persona | personas:read |
| PATCH | /personas/{id} | Update a persona | personas:write |
| DELETE | /personas/{id} | Delete a persona | personas:write |
| GET | /credits | Get workspace credits | credits:read |
| GET | /usage | Get API usage by mode | usage:read |
| POST | /webhooks | Create a signed webhook | webhooks:write |
| GET | /webhooks | List webhooks | webhooks:read |
| GET | /webhooks/{id} | Get a webhook | webhooks:read |
| DELETE | /webhooks/{id} | Delete a webhook | webhooks:write |
| GET | /webhooks/{id}/deliveries | List delivery attempts | webhooks:read |
Request and response details
All request and response schemas, field constraints, and reusable components are included in the OpenAPI download. The summaries below identify documented success and error responses; runtime checks may return additional errors described in troubleshooting.
GET /models
List available models.
Audio speech models include their full preset voice catalogue in capabilities.voices. Speech Lite voices include language, gender, styles, and preview metadata. Use /v1/voices/catalog for a filtered voice list.
Parameters:
mode(query, optional).
| Status | Description |
|---|---|
| 200 | Model catalogue |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
POST /files
Create a presigned media upload.
Use the returned upload_url with an HTTP PUT and the exact upload_headers, then pass url to a generation.
Request schema:
Parameters:
Idempotency-Key(header, optional).
| Status | Description |
|---|---|
| 201 | Upload created |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
POST /generations
Create image, video, or audio.
Request schema:
Parameters:
Idempotency-Key(header, optional).
| Status | Description |
|---|---|
| 202 | Generation queued |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 402 | Insufficient credits |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /generations
List API generations.
Parameters:
limit(query, optional).cursor(query, optional).
| Status | Description |
|---|---|
| 200 | Generation list |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /generations/{id}
Get generation status and outputs.
Parameters:
id(path, required).
| Status | Description |
|---|---|
| 200 | Generation |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 404 | Resource not found |
| 429 | Rate or concurrency limit exceeded |
POST /speech
Create multi-block speech.
Renders up to 50 voice blocks into one audio file. Use preset ids from /v1/voices/catalog for the selected model. Speech Cloning also accepts custom voice resource ids from /v1/voices.
Request schema:
Parameters:
Idempotency-Key(header, optional).
| Status | Description |
|---|---|
| 202 | Speech generation queued |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 402 | Insufficient credits |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /speech/{id}
Get multi-block speech status.
Parameters:
id(path, required).
| Status | Description |
|---|---|
| 200 | Speech generation |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 404 | Resource not found |
| 429 | Rate or concurrency limit exceeded |
GET /jobs/{id}
Poll any asynchronous job.
Parameters:
id(path, required).
| Status | Description |
|---|---|
| 200 | Generation or Agent run |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 404 | Resource not found |
| 429 | Rate or concurrency limit exceeded |
POST /agents/runs
Create an Agent production plan.
Plans require explicit approval unless auto_approve is true. Planning costs one credit; approved media steps reserve their maximum authorized budget.
Request schema:
Parameters:
Idempotency-Key(header, optional).
| Status | Description |
|---|---|
| 201 | Plan proposed |
| 202 | Plan approved and queued |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 402 | Insufficient credits |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /agents/runs
List Agent runs.
| Status | Description |
|---|---|
| 200 | Agent runs |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /agents/runs/{id}
Get an Agent run.
Parameters:
id(path, required).
| Status | Description |
|---|---|
| 200 | Agent run |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 404 | Resource not found |
| 429 | Rate or concurrency limit exceeded |
POST /agents/runs/{id}/approve
Approve an Agent plan.
Request schema:
Parameters:
id(path, required).Idempotency-Key(header, optional).
| Status | Description |
|---|---|
| 202 | Run queued or waiting |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 402 | Insufficient credits |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
POST /agents/runs/{id}/review
Complete the Agent review gate.
Request schema:
Parameters:
id(path, required).Idempotency-Key(header, optional).
| Status | Description |
|---|---|
| 200 | Completed run |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
POST /voices
Clone or design a voice.
Request schema:
Parameters:
Idempotency-Key(header, optional).
| Status | Description |
|---|---|
| 201 | Voice created |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 402 | Insufficient credits |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /voices
List custom voices.
| Status | Description |
|---|---|
| 200 | Voice list |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /voices/catalog
List language-specific preset voices.
Requires voices:read. Returns the complete preset catalogue without pagination, defaulting to Speech Lite. Pass an id as parameters.voice in /v1/generations or blocks[].voice in /v1/speech with the same model. /v1/voices lists workspace-owned custom voices separately.
Parameters:
model(query, optional).language(query, optional).gender(query, optional).search(query, optional).
| Status | Description |
|---|---|
| 200 | Preset voice catalogue |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /voices/{id}
Get a custom voice.
Parameters:
id(path, required).
| Status | Description |
|---|---|
| 200 | Voice |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
PATCH /voices/{id}
Rename a custom voice.
Request schema:
Parameters:
id(path, required).
| Status | Description |
|---|---|
| 200 | Voice updated |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
DELETE /voices/{id}
Delete a custom voice.
Parameters:
id(path, required).
| Status | Description |
|---|---|
| 200 | Voice deleted |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
POST /personas
Create a reusable visual persona.
Request schema:
Parameters:
Idempotency-Key(header, optional).
| Status | Description |
|---|---|
| 201 | Upload-backed persona created |
| 202 | Described persona queued |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /personas
List personas.
| Status | Description |
|---|---|
| 200 | Persona list |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /personas/{id}
Get a persona.
Parameters:
id(path, required).
| Status | Description |
|---|---|
| 200 | Persona |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
PATCH /personas/{id}
Update a persona.
Request schema:
Parameters:
id(path, required).
| Status | Description |
|---|---|
| 200 | Persona updated |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
DELETE /personas/{id}
Delete a persona.
Parameters:
id(path, required).
| Status | Description |
|---|---|
| 200 | Persona deleted |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /credits
Get workspace credits.
| Status | Description |
|---|---|
| 200 | Credit balance |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /usage
Get API usage by mode.
Parameters:
since(query, optional).
| Status | Description |
|---|---|
| 200 | Usage summary |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
POST /webhooks
Create a signed webhook.
Request schema:
Parameters:
Idempotency-Key(header, optional).
| Status | Description |
|---|---|
| 201 | Webhook and one-time signing secret |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /webhooks
List webhooks.
| Status | Description |
|---|---|
| 200 | Webhook list |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /webhooks/{id}
Get a webhook.
Parameters:
id(path, required).
| Status | Description |
|---|---|
| 200 | Webhook |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
DELETE /webhooks/{id}
Delete a webhook.
Parameters:
id(path, required).
| Status | Description |
|---|---|
| 200 | Webhook deleted |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |
GET /webhooks/{id}/deliveries
List delivery attempts.
Parameters:
id(path, required).
| Status | Description |
|---|---|
| 200 | Delivery list |
| 400 | Invalid request |
| 401 | Invalid or missing API key |
| 403 | Missing scope or API entitlement |
| 429 | Rate or concurrency limit exceeded |