{"openapi":"3.0.3","info":{"title":"Verbafy API","version":"1.0.0","description":"Paste a YouTube, Spotify URL or upload an audio/video file and get a transcript with named speakers, timestamps, and export-ready files. Same-origin REST at https://verbafy.io/api/v1. Auth-gated routes still appear here with security schemes. There is no GraphQL API.","contact":{"name":"Verbafy","url":"https://verbafy.io/contact","email":"support@verbafy.io"}},"servers":[{"url":"https://verbafy.io","description":"Public origin"}],"tags":[{"name":"Transcripts","description":"Create, list, poll, retry, and delete transcripts."},{"name":"Chat","description":"Transcript chat for one owned transcript."},{"name":"Uploads","description":"Private multipart upload reservations."},{"name":"Billing","description":"Plan, catalog, checkout, and portal."},{"name":"Auth","description":"Guest session create, revoke, and claim."},{"name":"Preferences","description":"Translation language and transcript layout."},{"name":"ApiKeys","description":"Registered User API keys for Remote MCP."},{"name":"Mcp","description":"Remote MCP Streamable HTTP transport. JSON-RPC methods are not REST operations."}],"paths":{"/api/v1/auth/guest-sessions":{"post":{"operationId":"createGuestSession","tags":["Auth"],"summary":"Create or reuse a Guest session","description":"Creates a seven-day Guest session cookie when none is valid. Production may require turnstileToken. New creates are limited to 3 per client IP per 3600 seconds.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGuestSessionBody"}}}},"responses":{"200":{"description":"Guest session created or reused","headers":{"Set-Cookie":{"description":"verbafy_guest_session when a new token is issued","schema":{"type":"string"}},"RateLimit":{"description":"IETF RateLimit, e.g. \"guest_session_create\";r=2;t=3600","schema":{"type":"string"}},"RateLimit-Policy":{"description":"IETF RateLimit-Policy, e.g. \"guest_session_create\";q=3;w=3600","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestSessionCreated"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Turnstile, ownership, or permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Guest-session create rate limit for this client IP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/auth/guest-sessions/current":{"delete":{"operationId":"revokeCurrentGuestSession","tags":["Auth"],"summary":"Revoke the current Guest session","description":"Clears the guest cookie and revokes the hashed token.","responses":{"204":{"description":"Guest session revoked"},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/auth/guest-sessions/claim":{"post":{"operationId":"claimGuestSession","tags":["Auth"],"summary":"Claim Guest data onto a Registered User","description":"Browser transition that moves Guest Transcripts and Chats onto the Clerk Registered User. Requires both a Clerk Bearer token and the Guest session cookie. Agents should not call this route.","security":[{"bearerAuth":[],"cookieAuth":[]}],"responses":{"200":{"description":"Claim result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuestClaimResult"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Conflict with current resource state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/transcripts":{"post":{"operationId":"createTranscript","tags":["Transcripts"],"summary":"Create a transcript from a public URL","description":"Accepts a YouTube or Spotify episode URL. Returns 200 when the enhanced transcript is ready, or 202 while processing.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTranscriptBody"},"example":{"url":"https://www.youtube.com/watch?v=VIDEO_ID"}}}},"responses":{"200":{"description":"Transcript ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptDetail"}}}},"202":{"description":"Transcript accepted and still processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptDetail"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Plan or usage does not include this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Upstream processing failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"operationId":"listTranscripts","tags":["Transcripts"],"summary":"List transcripts for the current account","description":"Paginated history. Empty channel filters are not query parameters here; the product filter is client-side.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"description":"Page size"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Page offset"}],"responses":{"200":{"description":"Transcript history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptHistory"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/transcripts/statuses":{"get":{"operationId":"listTranscriptStatuses","tags":["Transcripts"],"summary":"Batch-read transcript statuses","description":"ids is a comma-separated list of transcript UUIDs owned by the current account.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated transcript UUIDs"}],"responses":{"200":{"description":"Status list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptStatusList"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/transcripts/{id}":{"get":{"operationId":"getTranscript","tags":["Transcripts"],"summary":"Get one transcript","description":"Returns the owned transcript detail, including work body when ready.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TranscriptId"}],"responses":{"200":{"description":"Transcript detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptDetail"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found for the current account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"deleteTranscript","tags":["Transcripts"],"summary":"Delete one transcript","description":"Deletes the transcript. Related private media is removed with its last transcript.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TranscriptId"}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found for the current account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/transcripts/{id}/status":{"get":{"operationId":"getTranscriptStatus","tags":["Transcripts"],"summary":"Poll one transcript status","description":"Lightweight status for processing transcripts.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TranscriptId"}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptStatus"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found for the current account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/transcripts/{id}/captions":{"get":{"operationId":"getTranscriptCaptions","tags":["Transcripts"],"summary":"Get YouTube caption preview","description":"Returns a caption preview when one exists. Not a substitute for the enhanced transcript.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TranscriptId"}],"responses":{"200":{"description":"Caption preview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewTranscript"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found for the current account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/transcripts/{id}/retry":{"post":{"operationId":"retryTranscript","tags":["Transcripts"],"summary":"Retry a failed transcript","description":"Re-queues processing. Status may be 204, 202, or 200 depending on current state.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TranscriptId"}],"responses":{"200":{"description":"Already ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptDetail"}}}},"202":{"description":"Retry accepted"},"204":{"description":"No content retry accepted"},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Plan or usage does not include this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found for the current account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/transcripts/{id}/chat":{"get":{"operationId":"getTranscriptChat","tags":["Chat"],"summary":"Get transcript chat","description":"Returns the chat session, readiness, and messages for one owned transcript.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TranscriptId"}],"responses":{"200":{"description":"Chat","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptChat"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found for the current account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/transcripts/{id}/chat/messages":{"post":{"operationId":"sendTranscriptChatMessage","tags":["Chat"],"summary":"Send a chat message","description":"Adds a user message and returns the assistant reply with citations.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TranscriptId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendChatMessageBody"},"example":{"content":"Summarize the main claims."}}}},"responses":{"200":{"description":"User and assistant messages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendChatMessageResult"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Plan or usage does not include this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Conflict with current resource state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/transcripts/{id}/chat/messages/{messageId}/rating":{"put":{"operationId":"rateTranscriptChatMessage","tags":["Chat"],"summary":"Rate a chat message","description":"Sets or clears an up/down rating on one assistant message.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"$ref":"#/components/parameters/TranscriptId"},{"name":"messageId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Chat message UUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateChatMessageBody"},"example":{"rating":"up"}}}},"responses":{"200":{"description":"Updated message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateChatMessageResult"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found for the current account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/transcript-uploads":{"post":{"operationId":"createTranscriptUpload","tags":["Uploads"],"summary":"Reserve a private multipart upload","description":"Returns a reservation or an existing transcript when the content hash matches. Clients then sign parts and complete. Do not send storage credentials to browsers.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTranscriptUploadBody"},"example":{"filename":"meeting.m4a","bytes":1048576,"contentSha256":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}}}},"responses":{"200":{"description":"Reservation or duplicate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTranscriptUploadResult"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Plan or usage does not include this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Conflict with current resource state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/transcript-uploads/{id}/parts":{"post":{"operationId":"signTranscriptUploadPart","tags":["Uploads"],"summary":"Sign one multipart part","description":"Returns a short-lived signed URL for one part number.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"$ref":"#/components/parameters/UploadId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignTranscriptUploadPartBody"},"example":{"partNumber":1}}}},"responses":{"200":{"description":"Signed part URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedTranscriptUploadPart"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found for the current account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/transcript-uploads/{id}/complete":{"post":{"operationId":"completeTranscriptUpload","tags":["Uploads"],"summary":"Complete a multipart upload","description":"Validates parts server-side and starts transcription. May return 200 or 202.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"$ref":"#/components/parameters/UploadId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteTranscriptUploadBody"},"example":{"parts":[{"partNumber":1,"etag":"part-etag"}]}}}},"responses":{"200":{"description":"Transcript ready or already present","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptDetail"}}}},"202":{"description":"Upload completed; transcript processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptDetail"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found for the current account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Conflict with current resource state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/transcript-uploads/{id}":{"delete":{"operationId":"cancelTranscriptUpload","tags":["Uploads"],"summary":"Cancel a reservation","description":"Cancels an in-progress private upload reservation.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"$ref":"#/components/parameters/UploadId"}],"responses":{"204":{"description":"Cancelled"},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found for the current account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/billing/me":{"get":{"operationId":"getBillingMe","tags":["Billing"],"summary":"Get current plan and usage","description":"Returns plan, usage window, and limits for the current account.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Billing snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingMe"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/billing/catalog":{"get":{"operationId":"getBillingCatalog","tags":["Billing"],"summary":"Get public price catalog","description":"Public. No authentication. May be cached.","responses":{"200":{"description":"Catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCatalog"}}}},"502":{"description":"Upstream processing failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Dependency unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/billing/pricing-context":{"get":{"operationId":"getBillingPricingContext","tags":["Billing"],"summary":"Get pricing context","description":"Anonymous, Guest, or Registered. Always private, no-store.","security":[{"bearerAuth":[]},{"cookieAuth":[]},{}],"responses":{"200":{"description":"Pricing context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPricingContext"}}}}}}},"/api/v1/billing/checkout":{"post":{"operationId":"createBillingCheckout","tags":["Billing"],"summary":"Start a paid plan checkout","description":"Starts Starter or Pro checkout for weekly or monthly.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCheckoutBody"},"example":{"plan":"starter","interval":"monthly"}}}},"responses":{"200":{"description":"Checkout URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingUrl"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/billing/change-plan":{"post":{"operationId":"changeBillingPlan","tags":["Billing"],"summary":"Change the paid plan","description":"Changes Starter or Pro and interval for an existing subscription.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingCheckoutBody"},"example":{"plan":"starter","interval":"monthly"}}}},"responses":{"200":{"description":"Changed plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePlanResult"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/billing/convert-trial":{"post":{"operationId":"convertBillingTrial","tags":["Billing"],"summary":"Convert a paid-plan trial","description":"Ends a paid-plan trial on the same plan so the period becomes billed.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Converted trial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePlanResult"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/billing/portal":{"post":{"operationId":"createBillingPortal","tags":["Billing"],"summary":"Create a Stripe billing portal session","description":"Returns a URL for plan and payment management.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPortalBody"}}}},"responses":{"200":{"description":"Portal URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingUrl"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/me/preferences":{"get":{"operationId":"getPreferences","tags":["Preferences"],"summary":"Get preferences","description":"Translation language for the current account.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"Preferences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPreferences"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"operationId":"patchPreferences","tags":["Preferences"],"summary":"Update preferences","description":"Partial update. Clearing translation language keeps the original language.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreferencePatch"},"example":{"targetTranslationLanguage":"es"}}}},"responses":{"200":{"description":"Updated preferences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPreferences"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/me/api-keys":{"get":{"operationId":"listApiKeys","tags":["ApiKeys"],"summary":"List API keys","description":"Hashed API Key metadata for the current Registered User. Guests receive 403. Secrets are never listed.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"responses":{"200":{"description":"API keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyList"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Turnstile, ownership, or permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"createApiKey","tags":["ApiKeys"],"summary":"Create API key","description":"Create a named sk-… API Key. The secret is shown once. Registered Users only.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyBody"},"example":{"name":"local-agent"}}}},"responses":{"201":{"description":"Created API key including the secret once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedApiKey"}}}},"400":{"description":"Validation or domain request error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Turnstile, ownership, or permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Conflict with current resource state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/me/api-keys/{id}":{"delete":{"operationId":"revokeApiKey","tags":["ApiKeys"],"summary":"Revoke API key","description":"Revoke one API Key owned by the current Registered User.","security":[{"bearerAuth":[]},{"cookieAuth":[]}],"parameters":[{"$ref":"#/components/parameters/ApiKeyId"}],"responses":{"204":{"description":"Revoked"},"401":{"description":"Missing or invalid Clerk Bearer token or guest session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Turnstile, ownership, or permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Resource not found for the current account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/v1/mcp":{"post":{"operationId":"mcpPost","tags":["Mcp"],"summary":"Remote MCP Streamable HTTP","description":"Companion to this OpenAPI contract at https://verbafy.io/api/v1/mcp. Authenticate with Authorization: Bearer sk-…. JSON-RPC methods are MCP tools, not REST operations. Guests cannot call MCP.","security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"MCP Streamable HTTP response"},"401":{"description":"Missing or invalid API Key Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"operationId":"mcpGet","tags":["Mcp"],"summary":"Remote MCP Streamable HTTP GET","description":"Same Streamable HTTP endpoint as POST. API Key Bearer required.","security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"MCP Streamable HTTP response"},"401":{"description":"Missing or invalid API Key Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"operationId":"mcpDelete","tags":["Mcp"],"summary":"Remote MCP Streamable HTTP DELETE","description":"Same Streamable HTTP endpoint as POST. API Key Bearer required.","security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"MCP Streamable HTTP response"},"401":{"description":"Missing or invalid API Key Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Clerk session JWT for a Registered User. Clerk issues it after website login. Verbafy does not issue or display this token. Browser clients send it from the Clerk session. Scripts and agents create an API key under Settings → API keys and use apiKeyAuth on Remote MCP."},"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Registered User API Key for Remote MCP. Prefix sk-. Create the key under Settings → API keys after website login. Shown once at creation. Current keys are full-access for that Registered User. Request least privilege with the oauth2 scopes on this spec."},"cookieAuth":{"type":"apiKey","in":"cookie","name":"verbafy_guest_session","description":"Opaque Guest session cookie."},"oauth2":{"type":"oauth2","description":"Named Verbafy API capability scopes from RFC 9728. Clerk authorization and token URLs are listed so agents can find the user OIDC server. Clerk tokens use openid, email, and profile only; they do not include these scope names. Current sk- keys and Clerk session JWTs authorize the full account. These names are the least-privilege grants agents should request.","flows":{"authorizationCode":{"authorizationUrl":"https://clerk.verbafy.io/oauth/authorize","tokenUrl":"https://clerk.verbafy.io/oauth/token","scopes":{"transcripts:read":"Read owned transcripts, summaries, captions, and library lists.","transcripts:write":"Create, retry, and delete transcripts.","uploads:write":"Reserve, upload, and complete private media.","chat:write":"Read and send transcript chat messages.","billing:write":"Create Stripe Checkout and Customer Portal sessions.","keys:write":"List, create, and revoke Registered User API keys.","mcp":"Call Remote MCP tools with a Registered User API key.","preferences:write":"Read and update translation language and transcript layout."}}}},"clerkOidc":{"type":"openIdConnect","openIdConnectUrl":"https://clerk.verbafy.io/.well-known/openid-configuration","description":"Clerk OpenID Connect for Registered User browser REST. Machine MCP callers use apiKeyAuth."}},"parameters":{"TranscriptId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Transcript UUID owned by the current account"},"UploadId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Transcript upload reservation UUID"},"ApiKeyId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"API Key UUID owned by the current Registered User"}},"schemas":{"ApiIssue":{"type":"object","required":["path","code","message"],"properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}},"ApiError":{"type":"object","required":["message","code","hint","issues"],"properties":{"message":{"type":"string"},"code":{"type":"string"},"hint":{"type":"string","description":"Resolution hint for clients and agents"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/ApiIssue"}}}},"CreateGuestSessionBody":{"type":"object","properties":{"turnstileToken":{"type":"string","minLength":1}}},"GuestSessionCreated":{"type":"object","required":["expiresAt"],"properties":{"expiresAt":{"type":"string","format":"date-time"}}},"GuestClaimResult":{"type":"object","required":["claimed","movedUserTranscripts","skippedDuplicateTranscripts","movedChatSessions"],"properties":{"claimed":{"type":"boolean"},"movedUserTranscripts":{"type":"integer","minimum":0},"skippedDuplicateTranscripts":{"type":"integer","minimum":0},"movedChatSessions":{"type":"integer","minimum":0}}},"CreateTranscriptBody":{"type":"object","required":["url"],"properties":{"url":{"type":"string","minLength":1,"description":"Public YouTube URL or Spotify episode URL"}}},"TranscriptSource":{"oneOf":[{"type":"object","required":["type","videoId"],"properties":{"type":{"type":"string","enum":["youtube"]},"videoId":{"type":"string"}}},{"type":"object","required":["type","uploadId","originalFilename","extension","bytes"],"properties":{"type":{"type":"string","enum":["upload"]},"uploadId":{"type":"string"},"originalFilename":{"type":"string"},"extension":{"type":"string"},"bytes":{"type":"integer","nullable":true,"minimum":0}}},{"type":"object","required":["type","spotifyEpisodeId","episodeUrl","podcastTitle"],"properties":{"type":{"type":"string","enum":["spotify"]},"spotifyEpisodeId":{"type":"string"},"episodeUrl":{"type":"string"},"podcastTitle":{"type":"string"}}}]},"TranscriptResource":{"type":"object","required":["id","source","videoId","title","channel","channelAvatarUrl","durationSeconds","thumbnailUrl","playbackUrl","playbackMimeType","status","transcriptReady","previewReady","chatReady","numSpeakers","errorMessage","createdAt","readyAt"],"properties":{"id":{"type":"string","format":"uuid"},"source":{"$ref":"#/components/schemas/TranscriptSource"},"videoId":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"channel":{"type":"string","nullable":true},"channelAvatarUrl":{"type":"string","nullable":true},"durationSeconds":{"type":"number","nullable":true},"thumbnailUrl":{"type":"string","nullable":true},"playbackUrl":{"type":"string","nullable":true},"playbackMimeType":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","processing","ready","failed"]},"transcriptReady":{"type":"boolean"},"previewReady":{"type":"boolean"},"chatReady":{"type":"boolean"},"numSpeakers":{"type":"integer","minimum":0},"errorMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"readyAt":{"type":"string","format":"date-time","nullable":true}}},"WorkBodySegment":{"type":"object","required":["text","start","end"],"properties":{"text":{"type":"string"},"start":{"type":"number"},"end":{"type":"number"},"speaker_id":{"type":"integer"}}},"WorkBody":{"type":"object","required":["video_id","title","channel","segments","num_speakers","speaker_ids","speaker_names","summary","provider_transcript_id","source_language"],"properties":{"video_id":{"type":"string"},"title":{"type":"string"},"channel":{"type":"string","nullable":true},"segments":{"type":"array","items":{"$ref":"#/components/schemas/WorkBodySegment"}},"num_speakers":{"type":"integer","minimum":0},"speaker_ids":{"type":"array","items":{"type":"integer"}},"speaker_names":{"type":"object","additionalProperties":{"type":"string"}},"summary":{"type":"object","required":["overview","keyPoints"],"properties":{"overview":{"type":"string","nullable":true},"keyPoints":{"type":"array","items":{"type":"string"}}}},"translations":{"type":"object","additionalProperties":{"type":"object"}},"provider_transcript_id":{"type":"string","nullable":true},"source_language":{"type":"string","nullable":true}}},"PreviewTranscript":{"type":"object","required":["source","language","provenance","isOriginal","segments"],"properties":{"source":{"type":"string","enum":["youtube_captions"]},"language":{"type":"string"},"provenance":{"type":"string","enum":["manual","auto","auto_translated"]},"isOriginal":{"type":"boolean"},"segments":{"type":"array","items":{"$ref":"#/components/schemas/WorkBodySegment"}}}},"TranscriptDetail":{"allOf":[{"$ref":"#/components/schemas/TranscriptResource"},{"type":"object","required":["transcript","previewTranscript","targetTranslationLanguage","chatIndexStatus","canUseSummary","canExport"],"properties":{"transcript":{"allOf":[{"$ref":"#/components/schemas/WorkBody"}],"nullable":true},"previewTranscript":{"allOf":[{"$ref":"#/components/schemas/PreviewTranscript"}],"nullable":true},"targetTranslationLanguage":{"type":"string","nullable":true},"chatIndexStatus":{"type":"string","nullable":true,"enum":["pending","indexing","ready","failed"]},"canUseSummary":{"type":"boolean"},"canExport":{"type":"boolean"}}}]},"TranscriptHistory":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptResource"}},"pagination":{"type":"object","required":["limit","offset","count"],"properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"count":{"type":"integer","minimum":0}}}}},"TranscriptStatus":{"type":"object","required":["id","status","transcriptReady","previewReady","chatReady","chatIndexStatus","errorMessage","readyAt"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","ready","failed"]},"transcriptReady":{"type":"boolean"},"previewReady":{"type":"boolean"},"chatReady":{"type":"boolean"},"chatIndexStatus":{"type":"string","nullable":true,"enum":["pending","indexing","ready","failed"]},"errorMessage":{"type":"string","nullable":true},"readyAt":{"type":"string","format":"date-time","nullable":true}}},"TranscriptStatusList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptStatus"}}}},"ChatCitation":{"type":"object","required":["chunkId","segmentIndexStart","segmentIndexEnd","startSeconds","endSeconds","quote"],"properties":{"chunkId":{"type":"string"},"segmentIndexStart":{"type":"integer","minimum":0},"segmentIndexEnd":{"type":"integer","minimum":0},"startSeconds":{"type":"number"},"endSeconds":{"type":"number"},"quote":{"type":"string"}}},"TranscriptChatMessage":{"type":"object","required":["id","role","content","citations","rating","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"},"citations":{"type":"array","items":{"$ref":"#/components/schemas/ChatCitation"}},"rating":{"type":"string","nullable":true,"enum":["up","down"]},"createdAt":{"type":"string","format":"date-time"}}},"TranscriptChat":{"type":"object","required":["sessionId","transcriptReady","chatIndexStatus","chatReady","canUseChat","chatUserMessageLimit","chatUserMessageCount","messages"],"properties":{"sessionId":{"type":"string","format":"uuid","nullable":true},"transcriptReady":{"type":"boolean"},"chatIndexStatus":{"type":"string","nullable":true,"enum":["pending","indexing","ready","failed"]},"chatReady":{"type":"boolean"},"canUseChat":{"type":"boolean"},"chatUserMessageLimit":{"type":"integer","nullable":true,"minimum":1},"chatUserMessageCount":{"type":"integer","minimum":0},"messages":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptChatMessage"}}}},"SendChatMessageBody":{"type":"object","required":["content"],"properties":{"content":{"type":"string","minLength":1,"maxLength":4000}}},"SendChatMessageResult":{"type":"object","required":["userMessage","assistantMessage"],"properties":{"userMessage":{"$ref":"#/components/schemas/TranscriptChatMessage"},"assistantMessage":{"$ref":"#/components/schemas/TranscriptChatMessage"}}},"RateChatMessageBody":{"type":"object","required":["rating"],"properties":{"rating":{"type":"string","nullable":true,"enum":["up","down"]}}},"RateChatMessageResult":{"type":"object","required":["message"],"properties":{"message":{"$ref":"#/components/schemas/TranscriptChatMessage"}}},"CreateTranscriptUploadBody":{"type":"object","required":["filename","bytes","contentSha256"],"properties":{"filename":{"type":"string","minLength":1},"mimeType":{"type":"string"},"bytes":{"type":"number","minimum":1},"contentSha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}}},"CreateTranscriptUploadResult":{"oneOf":[{"type":"object","required":["kind","uploadId","expiresAt","maxBytes","partSizeBytes"],"properties":{"kind":{"type":"string","enum":["reserved"]},"uploadId":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"maxBytes":{"type":"number"},"partSizeBytes":{"type":"number"}}},{"type":"object","required":["kind","existingTranscriptId"],"properties":{"kind":{"type":"string","enum":["duplicate"]},"existingTranscriptId":{"type":"string","format":"uuid"}}}]},"SignTranscriptUploadPartBody":{"type":"object","required":["partNumber"],"properties":{"partNumber":{"type":"integer","minimum":1}}},"SignedTranscriptUploadPart":{"type":"object","required":["url","expiresAt"],"properties":{"url":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}},"CompleteTranscriptUploadBody":{"type":"object","required":["parts"],"properties":{"parts":{"type":"array","minItems":1,"items":{"type":"object","required":["partNumber","etag"],"properties":{"partNumber":{"type":"integer","minimum":1},"etag":{"type":"string","minLength":1}}}}}},"BillingMe":{"type":"object","required":["plan","status","billingInterval","cancelAtPeriodEnd","billingPeriodStart","billingPeriodEnd","usagePeriodStart","usagePeriodEnd","limits","usage","stripeCustomerId","canStartPaidPlanTrial"],"properties":{"plan":{"type":"string","enum":["free","starter","pro"]},"status":{"type":"string","enum":["active","free_trial","on_hold","cancelled","expired"]},"billingInterval":{"type":"string","nullable":true,"enum":["weekly","monthly","annual"]},"cancelAtPeriodEnd":{"type":"boolean"},"billingPeriodStart":{"type":"string","format":"date-time","nullable":true},"billingPeriodEnd":{"type":"string","format":"date-time","nullable":true},"usagePeriodStart":{"type":"string","format":"date-time"},"usagePeriodEnd":{"type":"string","format":"date-time"},"limits":{"type":"object","required":["maxTranscribedSecondsPerUsagePeriod","maxSecondsPerItem"],"properties":{"maxTranscribedSecondsPerUsagePeriod":{"type":"number"},"maxSecondsPerItem":{"type":"number"}}},"usage":{"type":"object","required":["transcriptCount","transcribedSeconds"],"properties":{"transcriptCount":{"type":"integer","minimum":0},"transcribedSeconds":{"type":"number","minimum":0}}},"stripeCustomerId":{"type":"string","nullable":true},"canStartPaidPlanTrial":{"type":"boolean"}}},"BillingCatalog":{"type":"object","required":["currency","plans"],"properties":{"currency":{"type":"string"},"plans":{"type":"object"}}},"BillingPricingContext":{"oneOf":[{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["guest"]}}},{"type":"object","required":["kind","plan","status","billingInterval","canStartPaidPlanTrial"],"properties":{"kind":{"type":"string","enum":["registered"]},"plan":{"type":"string","enum":["free","starter","pro"]},"status":{"type":"string"},"billingInterval":{"type":"string","nullable":true},"canStartPaidPlanTrial":{"type":"boolean"}}}]},"BillingCheckoutBody":{"type":"object","required":["plan"],"properties":{"plan":{"type":"string","enum":["starter","pro"]},"interval":{"type":"string","enum":["weekly","monthly"],"default":"monthly"}}},"BillingPortalBody":{"type":"object","properties":{"plan":{"type":"string","enum":["starter","pro"]},"interval":{"type":"string","enum":["weekly","monthly"]}}},"BillingUrl":{"type":"object","required":["url"],"properties":{"url":{"type":"string"}}},"ChangePlanResult":{"type":"object","required":["plan","billingInterval","refundCents","refundApplied","currentPeriodStart","currentPeriodEnd"],"properties":{"plan":{"type":"string","enum":["starter","pro"]},"billingInterval":{"type":"string","enum":["weekly","monthly"]},"refundCents":{"type":"integer"},"refundApplied":{"type":"boolean"},"currentPeriodStart":{"type":"string","format":"date-time"},"currentPeriodEnd":{"type":"string","format":"date-time"}}},"UserPreferences":{"type":"object","required":["targetTranslationLanguage"],"properties":{"targetTranslationLanguage":{"type":"string","nullable":true}}},"PreferencePatch":{"type":"object","properties":{"targetTranslationLanguage":{"type":"string","nullable":true}}},"CreateApiKeyBody":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100}}},"ApiKeyListItem":{"type":"object","required":["id","name","keyPrefix","createdAt","lastUsedAt"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"ApiKeyList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyListItem"}}}},"CreatedApiKey":{"type":"object","required":["id","name","keyPrefix","createdAt","lastUsedAt","secret"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"lastUsedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"secret":{"type":"string","description":"Full sk-… secret. Shown once."}}}}},"externalDocs":{"description":"Human API docs","url":"https://verbafy.io/docs"}}