{"openapi":"3.1.0","info":{"title":"Verbatim API","version":"1.0.0","summary":"Turn an article, YouTube video or transcript into an X thread, LinkedIn carousel, newsletter and video hooks.","description":"Verbatim repurposes one long-form source into draft social content in the account owner's voice (from voice samples saved in settings).\n\nAuthentication: create a personal API key at https://verbatimcoach.com/dashboard/settings#api-keys and send it as `Authorization: Bearer vb_...`.\n\nPlans: every successful generate call uses one draft from the same monthly allowance as the web app (Free: 3 drafts per calendar month (UTC); Pro $29/mo: unlimited). Failed generations are not counted.\n\nRate limits: 12 generate calls per 10 minutes per account (shared with the web app), 120 read calls per minute. Over the limit returns 429 with Retry-After.\n\nGeneration is synchronous: POST /v1/generate returns the finished result (typically 20 to 90 seconds). Fetch it again any time with GET /v1/generations/{id}.\n\nVerbatim never posts to social networks; it returns drafts.\n\nAn MCP server (Streamable HTTP) with the same capabilities is at https://verbatimcoach.com/api/mcp.","contact":{"name":"Verbatim support","email":"support@verbatimcoach.com","url":"https://verbatimcoach.com/docs/api"},"termsOfService":"https://verbatimcoach.com/terms"},"servers":[{"url":"https://verbatimcoach.com/api"}],"security":[{"bearerAuth":[]}],"externalDocs":{"url":"https://verbatimcoach.com/docs/api"},"paths":{"/v1/generate":{"post":{"operationId":"generateContent","summary":"Generate drafts from a URL, YouTube link or text","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"},"examples":{"article":{"value":{"input":"https://example.com/my-article","formats":["thread","carousel"]}},"youtube":{"value":{"input":"https://www.youtube.com/watch?v=VIDEO_ID","formats":["newsletter","hooks"]}},"text":{"value":{"sourceType":"text","input":"Notes or a transcript of at least a few paragraphs...","formats":["thread"]}}}}}},"responses":{"201":{"description":"Draft created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateResponse"}}}},"400":{"description":"Invalid request body (code invalid_request).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key (code unauthorized).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Monthly free allowance used up (code quota_exceeded).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Source could not be read or has too little substance (code unprocessable_source).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (code rate_limited).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/Error"},"502":{"description":"The AI writing service failed (code upstream_error). Not counted against usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/generations":{"get":{"operationId":"listGenerations","summary":"List recent drafts (newest first)","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Recent drafts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationList"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/generations/{id}":{"get":{"operationId":"getGeneration","summary":"Get a draft and all its outputs","parameters":[{"$ref":"#/components/parameters/GenerationId"}],"responses":{"200":{"description":"The draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/generations/{id}/pdf":{"get":{"operationId":"getCarouselPdf","summary":"Download the LinkedIn carousel as a PDF","parameters":[{"$ref":"#/components/parameters/GenerationId"}],"responses":{"200":{"description":"PDF file for a LinkedIn document post.","content":{"application/pdf":{"schema":{"type":"string","contentMediaType":"application/pdf"}}}},"401":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/me":{"get":{"operationId":"getAccount","summary":"Plan and remaining drafts this month","responses":{"200":{"description":"Account usage.","content":{"application/json":{"schema":{"type":"object","required":["object","email","usage"],"properties":{"object":{"const":"account"},"email":{"type":"string"},"usage":{"$ref":"#/components/schemas/Usage"}}}}}},"401":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal API key starting with vb_."}},"parameters":{"GenerationId":{"name":"id","in":"path","required":true,"schema":{"type":"string"}}},"responses":{"Error":{"description":"Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","quota_exceeded","not_found","method_not_allowed","rate_limited","unprocessable_source","upstream_error","internal_error"]},"message":{"type":"string"}}}}},"Format":{"type":"string","enum":["thread","carousel","newsletter","hooks"],"description":"thread = X thread, carousel = LinkedIn carousel, newsletter = newsletter draft, hooks = short-video hooks and script."},"GenerateRequest":{"type":"object","required":["input"],"additionalProperties":false,"properties":{"input":{"type":"string","maxLength":50000,"description":"A public article URL, a YouTube URL with captions, or pasted text."},"sourceType":{"type":"string","enum":["article","youtube","text"],"description":"Optional; inferred from input when omitted."},"formats":{"type":"array","items":{"$ref":"#/components/schemas/Format"},"minItems":1,"default":["thread","carousel"]}}},"Usage":{"type":"object","required":["plan","limit","used","remaining","periodResetsAt"],"properties":{"plan":{"type":"string","enum":["free","pro"]},"limit":{"type":["integer","null"],"description":"null on Pro (unlimited)."},"used":{"type":"integer"},"remaining":{"type":["integer","null"]},"periodResetsAt":{"type":"string","format":"date-time"}}},"Slide":{"type":"object","required":["kicker","headline","body"],"properties":{"kicker":{"type":"string"},"headline":{"type":"string"},"body":{"type":"string"}}},"Generation":{"type":"object","required":["id","object","status","createdAt","updatedAt","source","formats","outputs","links"],"properties":{"id":{"type":"string"},"object":{"const":"generation"},"status":{"const":"completed"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"source":{"type":"object","properties":{"type":{"type":"string","enum":["article","youtube","text"]},"url":{"type":["string","null"]},"title":{"type":"string"}}},"formats":{"type":"array","items":{"$ref":"#/components/schemas/Format"}},"outputs":{"type":"object","description":"Formats not requested are null.","properties":{"xThread":{"type":["array","null"],"items":{"type":"string"}},"carousel":{"type":["object","null"],"properties":{"title":{"type":"string"},"slides":{"type":"array","items":{"$ref":"#/components/schemas/Slide"}},"template":{"type":"string"},"brandColor":{"type":"string"}}},"newsletter":{"type":["object","null"],"properties":{"subject":{"type":"string"},"previewText":{"type":"string"},"intro":{"type":"string"},"sections":{"type":"array","items":{"type":"object","properties":{"heading":{"type":"string"},"body":{"type":"string"}}}},"cta":{"type":"string"}}},"videoHooks":{"type":["object","null"],"properties":{"hooks":{"type":"array","items":{"type":"string"}},"script":{"type":"object","properties":{"title":{"type":"string"},"lengthSeconds":{"type":"integer"},"beats":{"type":"array","items":{"type":"object","properties":{"time":{"type":"string"},"voiceover":{"type":"string"},"onScreenText":{"type":"string"}}}}}}}}}},"links":{"type":"object","properties":{"self":{"type":"string"},"edit":{"type":"string"},"carouselPdf":{"type":["string","null"]}}}}},"GenerateResponse":{"allOf":[{"$ref":"#/components/schemas/Generation"},{"type":"object","properties":{"usage":{"anyOf":[{"$ref":"#/components/schemas/Usage"},{"type":"null"}]}}}]},"GenerationList":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"source":{"type":"object"},"formats":{"type":"array","items":{"$ref":"#/components/schemas/Format"}}}}}}}}}}