The Verbato API

Send a recording from your own code and get back its transcript and the documents its project type writes. What a project type does in the app, a key can do here.

Version v1Read from the API's OpenAPI documentDownload it (JSON)

Get an API keyKeys are made in Settings, on the Business plan. See the plans

On this page

Quick start
Authentication
Errors
Limits
Webhooks
Projects
Documents
Transcript segments
Library
Usage
Webhooks

Quick start

Three steps take a recording through: send it, wait for it, read what came back.

Send a recording
From a link, in one call. A file goes in the same call as multipart/form-data; a large one goes to the address POST /api/v1/projects/upload-url gives you, and the project is created with the storageKey you were given.
Request
```
curl -X POST https://api.verbato.io/api/v1/projects \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sourceUrl":"https://example.com/supplier-interview.mp3","title":"Supplier interview"}'
```
Wait for it
Register a webhook once and Verbato calls you when a project completes or fails. Or ask for the project until its status is Completed or Failed.
Request
```
curl "https://api.verbato.io/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $VERBATO_KEY"
```
Read what came back
The transcript downloads in the format you ask for. The documents its project type wrote are listed by GET /api/v1/projects/{projectId}/documents, and each one exports as Markdown, text, Word or PDF.
Request
```
curl "https://api.verbato.io/api/v1/projects/$PROJECT_ID/transcript?format=txt" \
  -H "Authorization: Bearer $VERBATO_KEY" -o transcript.txt
```

Authentication

Every request carries your key as a bearer token:

HTTP

Authorization: Bearer sk_live_…

Keys are made in Settings → API. A new key is shown once, when it is made, and never again: keep it where your code keeps its secrets, never in a page or an app a visitor can read.

A key does the work: it sends recordings, reads what came back and changes the library. It does not act for the account: it cannot change the plan or the payment method, make or revoke keys, connect a channel, or delete the account or all of its projects at once. Those stay with a person signed in to the app.

Errors

A refusal answers with a status and, but for two, a body of one shape. error says what happened, in a sentence for a person. Where the refusal has a code, detail carries it: test the code, never the sentence, which can change. A 401, and a 429 for too many requests, carry no body.

Answer

{
  "error": "Concurrent job limit reached",
  "detail": "CONCURRENCY_LIMIT_REACHED"
}

Status	When
`400`	The request is not valid: a field missing, a file of a kind it does not take, a language Verbato does not transcribe.
`401`	No key, or a key that is not valid or was revoked.
`403`	The plan does not allow it: a key whose account is no longer on the plan with the API, for one.
`404`	Nothing by that id, or it belongs to another account.
`409`	The hours do not cover the recording, when a held one is started or one is transcribed again. The answer gives the minutes needed and the minutes available.
`429`	Too many requests for the key, or as many recordings running as the plan allows. Nothing is queued: send it again later.

Limits

Each key: 100 requests a minute and 10,000 a day. Past either, the answer is 429, and its Retry-After header says how many seconds to wait.

Recordings at once and the hours are the plan's, the same as in the app. A key that starts one recording more than the plan runs at once gets 429, and nothing is queued: send it again when one finishes. See the plans.

Webhooks

Register an https address once with POST /api/v1/webhooks, and Verbato calls it when one of the account's projects completes or fails: the events project.completed and project.failed. The answer to the registration carries the webhook's secret, once.

Each call is a POST with this body, and the event again in X-Verbato-Event:

What Verbato sends

{
  "id": "6f1c3e0a-…",
  "event": "project.completed",
  "createdAt": "2026-10-19T14:02:11Z",
  "data": {
    "projectId": "3b9e1c2a-…",
    "title": "Supplier interview",
    "status": "Completed",
    "source": "api",
    "errorMessage": null,
    "createdAt": "2026-10-19T13:58:40Z",
    "completedAt": "2026-10-19T14:02:10Z"
  }
}

Check that a call came from Verbato before you act on it. X-Verbato-Signature reads t=<time>,v1=<signature>: the signature is the HMAC-SHA256, in hex, of the time, a dot and the body, made with the webhook's secret.

Answer with a 2xx within 15 seconds. A call that gets anything else is sent again, up to 3 more times, after 2, 10 and 30 seconds. After 10 events in a row that were not delivered, the webhook is switched off: delete it and register it again.

Check the signature (Node.js)

import crypto from "node:crypto";

// header: the X-Verbato-Signature value; body: the raw body, as it arrived
export function isFromVerbato(secret, header, body) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (!parts.t || !parts.v1) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${body}`)
    .digest("hex");
  return expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Reference

Every operation a key can call, read from the API's OpenAPI document. Download the document to generate a client in your language. swagger.json

Projects

A recording and everything made from it: send one, follow it, read its transcript, keep it or delete it.

POST/api/v1/projects/upload-url

Get a URL to upload a file to

Returns a URL to upload one audio or video file to, and the storageKey to create the project with once it is there. Upload the file to the URL with a PUT that carries the Content-Type declared here. The file's size is checked against the plan and its type against the kinds accepted, and the URL expires in 30 minutes.

Body

Field	Type	What it is
`fileName` required	string	The file's name, with its extension.
`contentType` required	string	The file's media type, such as audio/mpeg. The upload must carry the same Content-Type.
`fileSizeBytes` required	integer	The file's size in bytes.

Answers

200UploadUrlResponse
400error
429error

Request

curl -X POST https://api.verbato.io/api/v1/projects/upload-url \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"supplier-interview.m4a","contentType":"audio/mp4","fileSizeBytes":18324000}'

POST/api/v1/projects

Create a project

Creates a project from a recording and starts it. The recording is a file sent with the request (multipart/form-data), a file already uploaded to the URL from POST /api/v1/projects/upload-url (storageKey), or a link (sourceUrl). Once the transcript is done, the project's type writes its documents. When the account's hours do not cover the recording, the project is held (status QuotaBlocked) and starts by itself when they do. When as many recordings are running as the account allows, the request is refused with 429: send it again later.

Body, JSON

Field	Type	What it is
`storageKey`	string	The storageKey POST /api/v1/projects/upload-url returned, once the file is uploaded to its URL. Send this or sourceUrl.
`title`	string	The project's name. Left out, it is made from the file's name or the link.
`language`	string	The language spoken, as a code from the languages Verbato transcribes (GET /api/v1/usage, supportedLanguages), such as en, es or pt. Left out, it is identified from the recording. Any other code is refused with 400.
`enableDiarization`	boolean	Label who speaks when. Left out, the project type decides.
`sourceUrl`	string	A link to the recording instead of a file: a page of a supported video or audio site, or a file's own address. Send this or storageKey.
`projectTypeId`	uuid	The project type that writes the documents. Left out, the account's default (GET /api/v1/library/default-project-type).
`retentionDays`	integer	How many days to keep the project, from 1 to the most the plan allows. Left out, the account's default.
`documents`	array	Which of the project type's documents to write, each named by its templateId and instructionsId. Left out, all of them; an empty list, the transcript alone.

Body, a form with the file

Field	Type	What it is
`file` required	file	The recording: one audio or video file.
`title`	string	The project's name. Left out, it is made from the file's name or the link.
`language`	string	The language spoken, as a code from the languages Verbato transcribes (GET /api/v1/usage, supportedLanguages), such as en, es or pt. Left out, it is identified from the recording. Any other code is refused with 400.
`enableDiarization`	boolean	Label who speaks when. Left out, the project type decides.
`projectTypeId`	uuid	The project type that writes the documents. Left out, the account's default (GET /api/v1/library/default-project-type).
`retentionDays`	integer	How many days to keep the project, from 1 to the most the plan allows. Left out, the account's default.
`documents`	string	The same list as the JSON body's documents, sent as JSON text.

Answers

201Project
400error
403error
429error

Request

curl -X POST https://api.verbato.io/api/v1/projects \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sourceUrl":"https://example.com/supplier-interview.mp3","title":"Supplier interview"}'

GET/api/v1/projects

List projects

Returns the account's projects, newest first, a page at a time. A project transcribed again is listed once, as its newest version.

Parameters

Parameter	In	Type	What it is
`page`	query	integer	The page, from 1. By default `1`.
`pageSize`	query	integer	Projects a page, from 1 to 100. By default `20`.
`status`	query	string	Only projects with this status, such as Completed or Failed.
`source`	query	string	Only projects from this source: api for those sent with a key.
`search`	query	string	Only projects whose title contains this text.
`locale`	query	string	es for the Spanish names of the packs' project types. Left out, English.

Answers

200a page of ProjectList

Request

curl https://api.verbato.io/api/v1/projects \
  -H "Authorization: Bearer $VERBATO_KEY"

GET/api/v1/projects/{id}

Get a project

Returns a project: its settings, where it stands, why it failed if it did, and the first 50 segments of its transcript.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`locale`	query	string	es for the Spanish names of the packs' project types. Left out, English.

Answers

200ProjectDetail
404error

Request

curl "https://api.verbato.io/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $VERBATO_KEY"

PATCH/api/v1/projects/{id}

Rename a project

Sets the project's title, from 1 to 500 characters.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`locale`	query	string	es for the Spanish names of the packs' project types. Left out, English.

Body

Field	Type	What it is
`title`	string	The new title, from 1 to 500 characters.

Answers

200ProjectDetail
400error
404error

Request

curl -X PATCH "https://api.verbato.io/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $VERBATO_KEY"

DELETE/api/v1/projects/{id}

Delete a project

Deletes a project: its recording, transcript and documents are erased and a deletion receipt is written. A row with no title, file name, link or sender stays until the account is deleted.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

204
404error

Request

curl -X DELETE "https://api.verbato.io/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $VERBATO_KEY"

GET/api/v1/projects/{id}/transcript

Download the transcript

Downloads the transcript as it stands, with every edit, as a file: txt, srt, vtt, json, docx or pdf. A project that is not completed has none yet (400).

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`format`	query	string	txt, srt, vtt, json, docx or pdf. By default `txt`.
`subtitleStyle`	query	string	For srt and vtt: standard (lines as spoken), social-media (a few words a line), word (one word a line) or custom (maxWords a line). By default `standard`.
`maxWords`	query	integer	Words a line, from 1 to 15: needed with custom, and changes social-media's.

Answers

200a file
400error
403error
404error

Request

curl "https://api.verbato.io/api/v1/projects/$PROJECT_ID/transcript?format=txt" \
  -H "Authorization: Bearer $VERBATO_KEY" -o transcript.txt

GET/api/v1/projects/{id}/segments

List the transcript's segments

Returns the transcript segment by segment, with its edits, a page at a time. Filter by speaker, by text, or by time.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`page`	query	integer	The page, from 1. By default `1`.
`pageSize`	query	integer	Segments a page, from 1 to 100. By default `50`.
`speaker`	query	string	Only this speaker's segments.
`search`	query	string	Only segments whose text contains this.
`from`	query	number	Only segments that start at or after this second.
`to`	query	number	Only segments that end at or before this second.

Answers

200a page of TranscriptSegment
404error

Request

curl "https://api.verbato.io/api/v1/projects/$PROJECT_ID/segments" \
  -H "Authorization: Bearer $VERBATO_KEY"

PATCH/api/v1/projects/{id}/done

Mark a project done, or back in review

Marks a completed project done, or puts it back in review. Done is the reader's call, not the processing's: a time beside the status, never a status of its own. It changes nothing else: nothing is deleted, hidden or kept longer. Transcribing the project again, or writing a document again, clears it, because what was reviewed is no longer what the project holds.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Body

Field	Type	What it is
`done` required	boolean	true to mark the project done, false to put it back in review.

Answers

200ProjectDone
400error
404error

Request

curl -X PATCH "https://api.verbato.io/api/v1/projects/$PROJECT_ID/done" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"done":true}'

PATCH/api/v1/projects/{id}/retention

Set how long a project is kept

Sets how many days the project is kept, counted from the day it was created: from 1 to the most the plan allows. When the time is up, its recording, transcript and documents are deleted. A project held for hours must be started first (409).

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Body

Field	Type	What it is
`days` required	integer	Days to keep the project, counted from the day it was created: from 1 to the most the plan allows.

Answers

200Retention
400error
404error
409error

Request

curl -X PATCH "https://api.verbato.io/api/v1/projects/$PROJECT_ID/retention" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"days":30}'

PATCH/api/v1/projects/{id}/settings

Change a project's settings

Changes the settings that can still change, and answers which were applied and which were already locked. The project type can change until its documents are written; once they exist, the new type applies to the project and nothing already written is rewritten. documents picks which of the type's documents to write: absent leaves it as it is, an empty list means the transcript alone, and a new project type resets it. The language can change until transcription starts, and the speakers while the project is processing or once it is completed. Turning the speakers on for a completed project labels them from the audio it already has; when as many recordings are running as the account allows, that request is refused with 429 and nothing changes: send it again later.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Body

Field	Type	What it is
`projectTypeId`	uuid	A new project type, until its documents are written. Left out, unchanged.
`enableDiarization`	boolean	Label who speaks when. Left out, unchanged.
`language`	string	The language spoken, as a code from the languages Verbato transcribes, until transcription starts. An empty string returns it to automatic. Left out, unchanged.
`documents`	array	Which of the type's documents to write, each named by its templateId and instructionsId. Left out, unchanged; an empty list, the transcript alone.

Answers

200ApplyProjectSettingsResult
400error
403error
404error
429error

Request

curl -X PATCH "https://api.verbato.io/api/v1/projects/$PROJECT_ID/settings" \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/projects/{id}/retry

Retry a failed project

Starts a failed project again: its status goes back to Pending. Only a failed project can be retried (400). When as many recordings are running as the account allows, the request is refused with 429 and the project stays as it is: send it again later.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

200Project
400error
404error
429error

Request

curl -X POST "https://api.verbato.io/api/v1/projects/$PROJECT_ID/retry" \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/projects/{id}/resume

Start a project held for hours

Starts a project that was held because the account's hours did not cover it (status QuotaBlocked). It starts at once when the account has a free slot, and is queued (status Queued) when it has none. Hours already promised to queued or running projects do not count as available: while the hours are still short, the answer is 409 with requiredMinutes and availableMinutes. A held project also starts by itself when hours arrive.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

202Project
400error
404error
409error

Request

curl -X POST "https://api.verbato.io/api/v1/projects/$PROJECT_ID/resume" \
  -H "Authorization: Bearer $VERBATO_KEY"

GET/api/v1/projects/{id}/download-url

Get a link to the recording or the first transcript

Returns a link to download the project's original recording (format audio) or its transcript as first written, before any edit (format json). The link expires in 60 minutes. Any other format is refused with 400 and DOWNLOAD_FORMAT_UNSUPPORTED: the transcript as it stands, in txt, srt, vtt, docx or pdf, is GET /api/v1/projects/{id}/transcript.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`format`	query	string	audio for the original recording, json for the transcript as first written. Any other format is refused (400). By default `json`.

Answers

200DownloadUrlResponse
400error
403error
404error

Request

curl "https://api.verbato.io/api/v1/projects/$PROJECT_ID/download-url" \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/projects/{id}/retranscribe

Transcribe a project again

Creates a new project from the same recording with other settings (language, speakers). It keeps the project's type and document selection, so it writes the documents a first run writes; speakers left out follow the type. The new project is counted against the account's hours like any other, and they are counted first: when they do not cover the recording, the answer is 409 with requiredMinutes and availableMinutes, nothing starts and the original stays as it is. A language the plan does not transcribe, or a plan that cannot transcribe again, is refused with 403; as many recordings running as the account allows, with 429.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Body

Field	Type	What it is
`language`	string	The language spoken, as a code from the languages Verbato transcribes (GET /api/v1/usage, supportedLanguages). Left out, identified from the recording.
`enableDiarization`	boolean	Label who speaks when. Left out, the project type decides.

Answers

201RetranscribeResponse
400error
403error
404error
409error
429error

Request

curl -X POST "https://api.verbato.io/api/v1/projects/$PROJECT_ID/retranscribe" \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/projects/{id}/diarize

Add speaker labels

Labels the speakers of a completed project's transcript, from the audio it already has, without transcribing it again. A project that already has speaker labels is refused (400), and so is a plan without them (403). When as many recordings are running as the account allows, the request is refused with 429 and the project stays as it is: send it again later.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`locale`	query	string	es for the Spanish names of the packs' project types. Left out, English.

Answers

200ProjectDetail
400error
403error
404error
409error
429error

Request

curl -X POST "https://api.verbato.io/api/v1/projects/$PROJECT_ID/diarize" \
  -H "Authorization: Bearer $VERBATO_KEY"

GET/api/v1/projects/{id}/exports

List the transcript's export formats

Lists the transcript's export formats, each with its download path and whether it can be downloaded now: the project must be completed and the format allowed by the plan.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

200ProjectExports
404error

Request

curl "https://api.verbato.io/api/v1/projects/$PROJECT_ID/exports" \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/projects/{id}/share

Create or update a share link

Gives a completed project a link that anyone who has it can open to read its documents, and returns the link. A project already shared keeps its link. includeTranscript sets whether the link shows the transcript too; left out, the setting does not change.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Body

Field	Type	What it is
`includeTranscript`	boolean	Whether the link shows the transcript too. Left out, unchanged.

Answers

200ShareResponse
400error
404error

Request

curl -X POST "https://api.verbato.io/api/v1/projects/$PROJECT_ID/share" \
  -H "Authorization: Bearer $VERBATO_KEY"

DELETE/api/v1/projects/{id}/share

Revoke the share link

Removes the share link: it stops working, and sharing the project again makes a new one.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

204
404error

Request

curl -X DELETE "https://api.verbato.io/api/v1/projects/$PROJECT_ID/share" \
  -H "Authorization: Bearer $VERBATO_KEY"

Documents

What a project's type writes from its transcript: read it, correct it, write it again, export it.

GET/api/v1/projects/{projectId}/documents

List a project's documents

Parameters

Parameter	In	Type	What it is
`projectId` required	path	uuid

Answers

200a list of Document
404error

Request

curl "https://api.verbato.io/api/v1/projects/$PROJECT_ID/documents" \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/projects/{projectId}/documents

Write another document

Writes one more document for the project, from a template and instructions the account can see. It is written in the background (202): read it back once its status is Completed. Documents are not counted against the hours. A project may have a limited number of documents written for it; past it, the answer is 429.

Parameters

Parameter	In	Type	What it is
`projectId` required	path	uuid

Body

Field	Type	What it is
`templateId` required	uuid	The template the document is written from.
`instructionsId` required	uuid	The instructions it is written with.

Answers

202Document
400error
404error
429error

Request

curl -X POST "https://api.verbato.io/api/v1/projects/$PROJECT_ID/documents" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructionsId":"…","templateId":"…"}'

GET/api/v1/projects/{projectId}/documents/{documentId}

Get a document with its current content and version history

Parameters

Parameter	In	Type	What it is
`projectId` required	path	uuid
`documentId` required	path	uuid

Answers

200DocumentDetail
404error

Request

curl "https://api.verbato.io/api/v1/projects/$PROJECT_ID/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $VERBATO_KEY"

PUT/api/v1/projects/{projectId}/documents/{documentId}

Edit a document

Saves the content sent, from 1 to 200,000 characters, as a new version (kind Edited) and makes it current.

Parameters

Parameter	In	Type	What it is
`projectId` required	path	uuid
`documentId` required	path	uuid

Body

Field	Type	What it is
`content` required	string	The document's whole new content.

Answers

200DocumentDetail
400error
404error

Request

curl -X PUT "https://api.verbato.io/api/v1/projects/$PROJECT_ID/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"## Summary\n\nThe supplier confirmed the first delivery for March."}'

GET/api/v1/projects/{projectId}/documents/{documentId}/versions/{versionId}

Get one version's content

Parameters

Parameter	In	Type
`projectId` required	path	uuid
`documentId` required	path	uuid
`versionId` required	path	uuid

Answers

200DocumentVersionContent
404error

Request

curl "https://api.verbato.io/api/v1/projects/$PROJECT_ID/documents/$DOCUMENT_ID/versions/$VERSION_ID" \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/projects/{projectId}/documents/{documentId}/correct

Correct a document by saying what is wrong

Applies the correction to this document as a new version (kind Corrected). When the correction is a rule rather than a fact about this recording, Verbato also learns it, for the account to keep or drop in the app. The answer's marginTag says which: structure, tone or term when it was learned, once when it was not. Corrections are held to a lower rate than other requests, and a document takes a limited number of them; past either, the answer is 429.

Parameters

Parameter	In	Type	What it is
`projectId` required	path	uuid
`documentId` required	path	uuid

Body

Field	Type	What it is
`correction` required	string	What is wrong, in your own words.
`aboutSection`	string	The name of the section the correction is about, if it is about one: at most 1,000 characters.

Answers

200DocumentCorrectionResponse
400error
404error
429error
502error

Request

curl -X POST "https://api.verbato.io/api/v1/projects/$PROJECT_ID/documents/$DOCUMENT_ID/correct" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"correction":"The second supplier is Brightline, not Brightside."}'

POST/api/v1/projects/{projectId}/documents/{documentId}/regenerate

Write a document again

Writes a new version (kind Regenerated) in the background and makes it current; an edited version stays in the history. It counts toward the project's limit of documents written. When the template or the instructions it was written from no longer exist, the answer is 409.

Parameters

Parameter	In	Type	What it is
`projectId` required	path	uuid
`documentId` required	path	uuid

Answers

202Document
400error
404error
409error
429error

Request

curl -X POST "https://api.verbato.io/api/v1/projects/$PROJECT_ID/documents/$DOCUMENT_ID/regenerate" \
  -H "Authorization: Bearer $VERBATO_KEY"

GET/api/v1/projects/{projectId}/documents/{documentId}/export

Export a document

Exports the current version as a file: md, txt, docx or pdf. Exports are not counted against the hours.

Parameters

Parameter	In	Type	What it is
`projectId` required	path	uuid
`documentId` required	path	uuid
`format`	query	string	md, txt, docx or pdf. By default `md`.

Answers

200
400error
404error

Request

curl "https://api.verbato.io/api/v1/projects/$PROJECT_ID/documents/$DOCUMENT_ID/export?format=pdf" \
  -H "Authorization: Bearer $VERBATO_KEY" -o document.pdf

PUT/api/v1/projects/{projectId}/documents/{documentId}/current-version

Make a version current

Makes one of the document's versions current. An export is of the current version.

Parameters

Parameter	In	Type	What it is
`projectId` required	path	uuid
`documentId` required	path	uuid

Body

Field	Type	What it is
`versionId` required	uuid	The version to make current, one of the document's.

Answers

200DocumentDetail
400error
404error

Request

curl -X PUT "https://api.verbato.io/api/v1/projects/$PROJECT_ID/documents/$DOCUMENT_ID/current-version" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"versionId":"…"}'

Transcript segments

The transcript line by line: edit a line, rename a speaker, find and replace, mark a line.

PATCH/api/v1/projects/{id}/segments/{segmentId}

Edit a segment's text

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`segmentId` required	path	uuid

Body

Field	Type	What it is
`text` required	string	The segment's new text. It cannot be empty.

Answers

Request

curl -X PATCH "https://api.verbato.io/api/v1/projects/$PROJECT_ID/segments/$SEGMENT_ID" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"We ship on the first Monday of each month."}'

PATCH/api/v1/projects/{id}/segments/bulk

Find and replace text across the transcript

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Body

Field	Type	What it is
`find` required	string	The text to find.
`replace` required	string	The text to put in its place.
`caseSensitive`	boolean	Match upper and lower case exactly. Left out, false.
`wholeWord`	boolean	Match whole words only. Left out, false: the text is found inside words too.

Answers

Request

curl -X PATCH "https://api.verbato.io/api/v1/projects/$PROJECT_ID/segments/bulk" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"find":"Acme Ltd","replace":"Acme Limited"}'

PATCH/api/v1/projects/{id}/speakers/{oldLabel}/rename

Rename a speaker across the transcript

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`oldLabel` required	path	string

Body

Field	Type	What it is
`newLabel` required	string	The speaker's new name, on every segment that had the old one.

Answers

Request

curl -X PATCH "https://api.verbato.io/api/v1/projects/$PROJECT_ID/speakers/$OLD_LABEL/rename" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"newLabel":"Dana"}'

PATCH/api/v1/projects/{id}/segments/{segmentId}/speaker

Change one segment's speaker

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`segmentId` required	path	uuid

Body

Field	Type	What it is
`speaker`	string	The speaker of this segment. It cannot be empty.

Answers

Request

curl -X PATCH "https://api.verbato.io/api/v1/projects/$PROJECT_ID/segments/$SEGMENT_ID/speaker" \
  -H "Authorization: Bearer $VERBATO_KEY"

PATCH/api/v1/projects/{id}/segments/{segmentId}/revert

Put a segment back to the text first transcribed

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`segmentId` required	path	uuid

Answers

Request

curl -X PATCH "https://api.verbato.io/api/v1/projects/$PROJECT_ID/segments/$SEGMENT_ID/revert" \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/projects/{id}/segments/{segmentId}/bookmark

Bookmark a segment, or remove its bookmark

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`segmentId` required	path	uuid

Answers

Request

curl -X POST "https://api.verbato.io/api/v1/projects/$PROJECT_ID/segments/$SEGMENT_ID/bookmark" \
  -H "Authorization: Bearer $VERBATO_KEY"

GET/api/v1/projects/{id}/bookmarks

List a project's bookmarked segments

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

Request

curl "https://api.verbato.io/api/v1/projects/$PROJECT_ID/bookmarks" \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/projects/{id}/segments/{segmentId}/annotation

Add or change a segment's note

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`segmentId` required	path	uuid

Body

Field	Type	What it is
`noteText` required	string	The note's text.

Answers

Request

curl -X POST "https://api.verbato.io/api/v1/projects/$PROJECT_ID/segments/$SEGMENT_ID/annotation" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"noteText":"Check the delivery date with finance."}'

DELETE/api/v1/projects/{id}/segments/{segmentId}/annotation

Delete a segment's note

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`segmentId` required	path	uuid

Answers

Request

curl -X DELETE "https://api.verbato.io/api/v1/projects/$PROJECT_ID/segments/$SEGMENT_ID/annotation" \
  -H "Authorization: Bearer $VERBATO_KEY"

GET/api/v1/projects/{id}/annotations

List a project's segments with notes

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

Request

curl "https://api.verbato.io/api/v1/projects/$PROJECT_ID/annotations" \
  -H "Authorization: Bearer $VERBATO_KEY"

Library

The templates, instructions and project types that decide which documents a recording gets, and the packs that bring ready-made ones.

GET/api/v1/library/templates

List templates

The account's own templates and those of its installed packs, Core's included: Core is built in and installed on every account. A pack's template cannot be changed; duplicate it to make one of your own.

Parameters

Parameter	In	Type	What it is
`locale`	query	string	es for the Spanish text of the packs' objects. Left out, English.

Answers

200a list of Template

Request

curl https://api.verbato.io/api/v1/library/templates \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/library/templates

Create a template

Body

Field	Type	What it is
`name` required	string	A name for the document the template writes.
`description`	string	What the template is for. Optional.
`sections` required	array	The document's sections, in order.
`outputFormat`	string	markdown or plain. Left out, markdown.

Answers

201Template
400error

Request

curl -X POST https://api.verbato.io/api/v1/library/templates \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Supplier interview summary","sections":[{"name":"Supplier interview summary"}]}'

GET/api/v1/library/templates/{id}

Get a template

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`locale`	query	string	es for the Spanish text of the packs' objects. Left out, English.

Answers

200Template
404error

Request

curl "https://api.verbato.io/api/v1/library/templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $VERBATO_KEY"

PUT/api/v1/library/templates/{id}

Update one of your templates

A null or absent description keeps the stored one, and so does a null or absent outputFormat. An empty description clears it.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Body

Field	Type	What it is
`name` required	string	A name for the document the template writes.
`description`	string	What the template is for. Null or absent keeps the stored one; empty clears it.
`sections` required	array	The document's sections, in order. They replace the ones it has.
`outputFormat`	string	markdown or plain. Null or absent keeps the stored one.

Answers

200Template
400error
403error
404error

Request

curl -X PUT "https://api.verbato.io/api/v1/library/templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Supplier interview summary","sections":[{"name":"Supplier interview summary"}]}'

DELETE/api/v1/library/templates/{id}

Delete one of your templates

Refused (409) while a project type uses it.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

204
403error
404error
409error

Request

curl -X DELETE "https://api.verbato.io/api/v1/library/templates/$TEMPLATE_ID" \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/library/templates/{id}/section-state

Switch a section of one of your templates off or on

A section that is off stays in the template, with its name, its guidance and its place, and is not written. Applies from the next generation: documents already written are not touched. At least one section stays on.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Body

Field	Type	What it is
`index` required	integer	The section's place in the template, from 0.
`name` required	string	Its heading, which must match the section at that place.
`off` required	boolean	true to switch it off, false to switch it on.

Answers

200Template
403error
404error
409error

Request

curl -X POST "https://api.verbato.io/api/v1/library/templates/$TEMPLATE_ID/section-state" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"index":0,"name":"Supplier interview summary","off":true}'

POST/api/v1/library/templates/{id}/own-section-state

Switch a section off in your copy of a pack's template

A pack's template is never changed. With no copy of it yet, it is copied into your library with the section off, and the project type that writes it becomes one of your own too (201). With a copy, copyId names the one the section goes off in (200). It never replaces a copy and never makes a second one: 409 COPY_EXISTS when a copy exists and none was named.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Body

Field	Type	What it is
`index` required	integer	The section's place in the pack's template, from 0.
`name` required	string	Its heading, which must match the section at that place.
`instructionsId` required	uuid	The instructions the template is paired with.
`copyId`	uuid	Your copy to switch the section off in. Left out, a copy is made.
`projectTypeId`	uuid	The project type the template is written under.
`locale`	string	es to make the copy in Spanish. Left out, English.

Answers

200OwnSectionStateResponse
201OwnSectionStateResponse
404error
409error

Request

curl -X POST "https://api.verbato.io/api/v1/library/templates/$TEMPLATE_ID/own-section-state" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"index":0,"instructionsId":"…","name":"Supplier interview summary"}'

POST/api/v1/library/templates/{id}/duplicate

Duplicate a template into your library

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

201Template
404error

Request

curl -X POST "https://api.verbato.io/api/v1/library/templates/$TEMPLATE_ID/duplicate" \
  -H "Authorization: Bearer $VERBATO_KEY"

GET/api/v1/library/instructions

List instructions

The account's own instructions and those of its installed packs, Core's included. A pack's instructions cannot be changed; duplicate them to make your own. Rules for reading a recording are ordinary instructions.

Parameters

Parameter	In	Type	What it is
`locale`	query	string	es for the Spanish text of the packs' objects. Left out, English.

Answers

200a list of Instructions

Request

curl https://api.verbato.io/api/v1/library/instructions \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/library/instructions

Create instructions

Body

Field	Type	What it is
`name` required	string	A name, up to 200 characters.
`description`	string	What the instructions are for. Optional.
`rulesText` required	string	The rules the document is written by, as plain text.

Answers

201Instructions
400error

Request

curl -X POST https://api.verbato.io/api/v1/library/instructions \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Supplier interview summary","rulesText":"Write in plain sentences. Name each supplier as they were introduced."}'

GET/api/v1/library/instructions/{id}

Get instructions

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`locale`	query	string	es for the Spanish text of the packs' objects. Left out, English.

Answers

200Instructions
404error

Request

curl "https://api.verbato.io/api/v1/library/instructions/$INSTRUCTION_ID" \
  -H "Authorization: Bearer $VERBATO_KEY"

PUT/api/v1/library/instructions/{id}

Update your instructions

A null or absent description keeps the stored one. An empty description clears it.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Body

Field	Type	What it is
`name` required	string	A name, up to 200 characters.
`description`	string	What the instructions are for. Null or absent keeps the stored one; empty clears it.
`rulesText` required	string	The rules the document is written by, as plain text.

Answers

200Instructions
400error
403error
404error

Request

curl -X PUT "https://api.verbato.io/api/v1/library/instructions/$INSTRUCTION_ID" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Supplier interview summary","rulesText":"Write in plain sentences. Name each supplier as they were introduced."}'

DELETE/api/v1/library/instructions/{id}

Delete your instructions

Refused (409) while a project type uses them.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

204
403error
404error
409error

Request

curl -X DELETE "https://api.verbato.io/api/v1/library/instructions/$INSTRUCTION_ID" \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/library/instructions/{id}/duplicate

Duplicate instructions into your library

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

201Instructions
404error

Request

curl -X POST "https://api.verbato.io/api/v1/library/instructions/$INSTRUCTION_ID/duplicate" \
  -H "Authorization: Bearer $VERBATO_KEY"

GET/api/v1/library/project-types

List project types

The account's own project types and those of its installed packs. A project type is a named set of template and instructions pairs, from none upward: each pair writes one document.

Parameters

Parameter	In	Type	What it is
`locale`	query	string	es for the Spanish text of the packs' objects. Left out, English.

Answers

200a list of ProjectType

Request

curl https://api.verbato.io/api/v1/library/project-types \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/library/project-types

Create a project type

Body

Field	Type	What it is
`name` required	string	A name, up to 200 characters.
`description`	string	What the project type is for. Optional.
`pairs` required	array	The template and instructions pairs, one per document. May be empty: a project type that writes none, only the transcript.

Answers

201ProjectType
400error

Request

curl -X POST https://api.verbato.io/api/v1/library/project-types \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Supplier interview summary","pairs":[{"instructionsId":"…","templateId":"…"}]}'

GET/api/v1/library/project-types/{id}

Get a project type

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid
`locale`	query	string	es for the Spanish text of the packs' objects. Left out, English.

Answers

200ProjectType
404error

Request

curl "https://api.verbato.io/api/v1/library/project-types/$PROJECT_TYPE_ID" \
  -H "Authorization: Bearer $VERBATO_KEY"

PUT/api/v1/library/project-types/{id}

Update one of your project types

Replaces its pairs with the ones sent. A null or absent description keeps the stored one. An empty description clears it.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Body

Field	Type	What it is
`name` required	string	A name, up to 200 characters.
`description`	string	What the project type is for. Null or absent keeps the stored one; empty clears it.
`pairs` required	array	The pairs, which replace the ones it has. May be empty.

Answers

200ProjectType
400error
403error
404error

Request

curl -X PUT "https://api.verbato.io/api/v1/library/project-types/$PROJECT_TYPE_ID" \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Supplier interview summary","pairs":[{"instructionsId":"…","templateId":"…"}]}'

DELETE/api/v1/library/project-types/{id}

Delete one of your project types

Refused (409) while it is the account's default or a channel's.

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

204
403error
404error
409error

Request

curl -X DELETE "https://api.verbato.io/api/v1/library/project-types/$PROJECT_TYPE_ID" \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/library/project-types/{id}/duplicate

Duplicate a project type, with its pairs, into your library

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

201ProjectType
404error

Request

curl -X POST "https://api.verbato.io/api/v1/library/project-types/$PROJECT_TYPE_ID/duplicate" \
  -H "Authorization: Bearer $VERBATO_KEY"

GET/api/v1/library/default-project-type

Get the account's default project type

The account's default, when it has one it can still see; otherwise Core's Transcript + summary. A project created without a type gets this one.

Parameters

Parameter	In	Type	What it is
`locale`	query	string	es for the Spanish text of the packs' objects. Left out, English.

Answers

200ProjectType
404error

Request

curl https://api.verbato.io/api/v1/library/default-project-type \
  -H "Authorization: Bearer $VERBATO_KEY"

PUT/api/v1/library/default-project-type

Set the account's default project type

Body

Field	Type	What it is
`projectTypeId` required	uuid	A project type the account can see.

Answers

200ProjectType
404error

Request

curl -X PUT https://api.verbato.io/api/v1/library/default-project-type \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectTypeId":"…"}'

GET/api/v1/library/packs

List packs

Every pack, and whether the account has installed it. Core is built in and installed on every account.

Parameters

Parameter	In	Type	What it is
`locale`	query	string	es for the Spanish text of the packs' objects. Left out, English.

Answers

200a list of Pack

Request

curl https://api.verbato.io/api/v1/library/packs \
  -H "Authorization: Bearer $VERBATO_KEY"

GET/api/v1/library/packs/{key}/contents

See what a pack holds

The pack's project types, with the documents each one writes, its templates with their section names, and its specialties, whether the pack is installed or not. With a specialty, only the project types and templates tagged with it or with none.

Parameters

Parameter	In	Type	What it is
`key` required	path	string
`locale`	query	string	es for the Spanish text of the packs' objects. Left out, English.
`specialty`	query	string	A specialty key of the pack: only the project types and templates tagged with it, or tagged with none, are listed. Left out, every one.

Answers

200PackContents
404error

Request

curl "https://api.verbato.io/api/v1/library/packs/$PACK_KEY/contents" \
  -H "Authorization: Bearer $VERBATO_KEY"

POST/api/v1/library/packs/{key}/install

Install a pack

Installs the pack: its project types, templates and instructions join the account's. Installing a pack already installed changes nothing.

Parameters

Parameter	In	Type	What it is
`key` required	path	string
`source`	query	string	Where in the app the install was asked from. Leave it out: it changes nothing.
`specialty`	query	string	The specialty the install was asked for, one of the pack's. Leave it out: it changes nothing.

Answers

200Pack
404error

Request

curl -X POST "https://api.verbato.io/api/v1/library/packs/$PACK_KEY/install" \
  -H "Authorization: Bearer $VERBATO_KEY"

DELETE/api/v1/library/packs/{key}/install

Uninstall a pack

Core cannot be uninstalled. A default that names one of the pack's project types is reset; your own duplicates are not touched.

Parameters

Parameter	In	Type	What it is
`key` required	path	string

Answers

204
400error
404error

Request

curl -X DELETE "https://api.verbato.io/api/v1/library/packs/$PACK_KEY/install" \
  -H "Authorization: Bearer $VERBATO_KEY"

Usage

The account's hours and what it has used.

GET/api/v1/usage/hours

Get the account's hours

The minutes left in this period's allowance and in top-up packs, the period's dates, the minutes used in it, and the minutes metered past the allowance.

Answers

200HourUsage

Request

curl https://api.verbato.io/api/v1/usage/hours \
  -H "Authorization: Bearer $VERBATO_KEY"

GET/api/v1/usage/dashboard-stats

Get the account's statistics

Returns dashboard statistics including project counts (current and previous period for trend), total duration, top export format, and project breakdown by source channel.

Answers

200DashboardStats

Request

curl https://api.verbato.io/api/v1/usage/dashboard-stats \
  -H "Authorization: Bearer $VERBATO_KEY"

GET/api/v1/usage

Get the account's usage

Returns the account's usage: its projects this period against the plan's limit, their total duration in seconds, the jobs running and the most that may run at once, the plan, the billing period's dates, and whether the account opted out of analytics.

Answers

200Usage

Request

curl https://api.verbato.io/api/v1/usage \
  -H "Authorization: Bearer $VERBATO_KEY"

Webhooks

The addresses Verbato calls when a project completes or fails.

POST/api/v1/webhooks

Register a webhook

Registers an https address to call when one of the account's projects completes or fails. The answer carries the webhook's signing secret, the only time it is shown. An account may have 5 webhooks. What is sent, and how to check its signature, is under webhooks. An account whose plan does not include the API cannot register one: 403, with the code PLAN_UPGRADE_REQUIRED.

Body

Field	Type	What it is
`url` required	string	An https address of yours that answers POST.
`events`	array	project.completed, project.failed, or both. Left out, both.

Answers

201CreatedWebhook
400error
403error

Request

curl -X POST https://api.verbato.io/api/v1/webhooks \
  -H "Authorization: Bearer $VERBATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/verbato","events":["project.completed","project.failed"]}'

GET/api/v1/webhooks

List webhooks

The account's webhooks: each one's address and events, the start of its secret, whether it is on, when it last delivered, and how many deliveries in a row have failed.

Answers

200a list of Webhook

Request

curl https://api.verbato.io/api/v1/webhooks \
  -H "Authorization: Bearer $VERBATO_KEY"

DELETE/api/v1/webhooks/{id}

Delete a webhook

Parameters

Parameter	In	Type	What it is
`id` required	path	uuid

Answers

204
404error

Request

curl -X DELETE "https://api.verbato.io/api/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $VERBATO_KEY"

The Verbato API

Quick start

Send a recording

Wait for it

Read what came back

Authentication

Errors

Limits

Webhooks

Reference

Projects

Get a URL to upload a file to

Create a project

List projects

Get a project

Rename a project

Delete a project

Download the transcript

List the transcript's segments

Mark a project done, or back in review

Set how long a project is kept

Change a project's settings

Retry a failed project

Start a project held for hours

Get a link to the recording or the first transcript

Transcribe a project again

Add speaker labels

List the transcript's export formats

Create or update a share link

Revoke the share link

Documents

List a project's documents

Write another document

Get a document with its current content and version history

Edit a document

Get one version's content

Correct a document by saying what is wrong

Write a document again

Export a document

Make a version current

Transcript segments

Edit a segment's text

Find and replace text across the transcript

Rename a speaker across the transcript

Change one segment's speaker

Put a segment back to the text first transcribed

Bookmark a segment, or remove its bookmark

List a project's bookmarked segments

Add or change a segment's note

Delete a segment's note

List a project's segments with notes

Library

List templates

Create a template

Get a template

Update one of your templates

Delete one of your templates

Switch a section of one of your templates off or on

Switch a section off in your copy of a pack's template

Duplicate a template into your library

List instructions

Create instructions

Get instructions

Update your instructions

Delete your instructions

Duplicate instructions into your library

List project types

Create a project type

Get a project type

Update one of your project types

Delete one of your project types

Duplicate a project type, with its pairs, into your library

Get the account's default project type

Set the account's default project type

List packs

See what a pack holds

Install a pack

Uninstall a pack

Usage

Get the account's hours