---
title: "API docs"
description: "Authenticate and call the Verbafy REST API for transcripts, uploads, chat, and billing."
canonical: "https://verbafy.io/docs"
last-updated: "2026-09-23"
---

# API docs

Start with the [Developer resources](/developers) 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](/openapi.json). Agent authentication is [Auth.md](/auth.md). Human support is [support@verbafy.io](mailto: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 REST routes need a Clerk session JWT (`Authorization: Bearer {jwt}`) or the `verbafy_guest_session` cookie. `{jwt}` is a Clerk session token after you sign in on the website. The Verbafy browser app sends it 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](/app/settings/api-keys), and send `Authorization: Bearer sk-…`. Guests cannot use MCP. Credential setup and expiry: [Auth.md](/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](/docs/api). Each page includes curl, JavaScript, and Python. Markdown twins append `.md` (for example [/docs/api/transcripts/create-transcript.md](/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](/docs/api/transcripts/create-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`.

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://verbafy.io/#organization",
      "name": "Verbafy",
      "url": "https://verbafy.io",
      "inLanguage": "en",
      "knowsAbout": [
        "YouTube transcription",
        "Spotify episode transcription",
        "Meeting recording transcription",
        "Speaker diarization",
        "Transcript export"
      ],
      "hasOfferCatalog": {
        "@id": "https://verbafy.io/pricing#offers"
      },
      "contactPoint": {
        "@type": "ContactPoint",
        "contactType": "customer support",
        "email": "support@verbafy.io",
        "url": "https://verbafy.io/contact"
      }
    },
    {
      "@type": "TechArticle",
      "@id": "https://verbafy.io/docs#page",
      "name": "API docs",
      "description": "Authenticate and call the Verbafy REST API for transcripts, uploads, chat, and billing.",
      "url": "https://verbafy.io/docs",
      "inLanguage": "en",
      "isPartOf": {
        "@id": "https://verbafy.io/#website"
      },
      "publisher": {
        "@id": "https://verbafy.io/#organization"
      }
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Home",
          "item": "https://verbafy.io"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "API docs",
          "item": "https://verbafy.io/docs"
        }
      ]
    }
  ]
}
```