Verbafy

API docs

Start with the Developer resources REST or MCP quickstart. The REST API is https://verbafy.io/api/v1. Browser clients use that same-origin path. The machine-readable contract is OpenAPI. Agent authentication is Auth.md. Human support is support@verbafy.io.

When to call this API

Use this API when a person needs a speaker-labeled transcript of a public YouTube video, a Spotify episode URL, or a private upload, then wants timestamps, exports, or transcript chat. Do not use it as a live meeting bot or as a generic speech-to-text dump.

Authentication

Most account REST routes accept one browser session credential: a Clerk session JWT (Authorization: Bearer {jwt}) for a Registered User, or the verbafy_guest_session cookie for a Guest. Some routes are Registered User only. {jwt} is a Clerk session token after you sign in on the website. The Verbafy browser app sends the applicable credential automatically. Verbafy does not issue that token and does not show it in Settings. Do not look for a JWT to copy.

Create a Guest session with POST /api/v1/auth/guest-sessions. Production Guest creates require a Turnstile token when Turnstile is configured.

Remote MCP is a companion to this REST contract at https://verbafy.io/api/v1/mcp (Streamable HTTP). For scripts and agents, sign in, create an API key at Settings → API keys, and send Authorization: Bearer sk-…. An API key authenticates Remote MCP, not REST. Guests cannot use MCP. Credential setup and expiry: Auth.md.

Named API capability scopes (transcripts:read, transcripts:write, uploads:write, chat:write, billing:write, keys:write, mcp, preferences:write) are declared on the OpenAPI oauth2 scheme and on RFC 9728 scopes_supported. Current keys still authorize the full account. Clerk OIDC tokens use Clerk scopes (openid, email, profile), not those API grants.

API reference

Generated operation pages live under API reference. Each page includes curl, JavaScript, and Python. Markdown twins append .md (for example /docs/api/transcripts/create-transcript.md). Customer webhook subscriptions are not supported.

Example: create a transcript

Send POST /api/v1/transcripts with Content-Type: application/json and body {"url":"https://www.youtube.com/watch?v=VIDEO_ID"}. The handler returns 200 when the enhanced transcript is ready, or 202 while it is still processing. Poll GET /api/v1/transcripts/{id}/status. Full snippets: create a transcript.

Chat and uploads

GET /api/v1/transcripts/{id}/chat and POST /api/v1/transcripts/{id}/chat/messages need the same account auth. Private files use POST /api/v1/transcript-uploads, signed parts, then complete. Do not send storage credentials to a client.

Errors and rate limits

Errors are JSON: { message, code, hint, issues }. Only new Guest session creates are application-rate-limited today: 3 per client IP per 3600 seconds. Those responses send RateLimit and RateLimit-Policy. A 429 also sends Retry-After.

Remote MCP at /api/v1/mcp is a companion wrap of this REST contract.