API guide

Use Claravo from your own programs: list and read your decks, export them, and start new ones. Every call acts as your account and meets the same checks as the app: the same decks you can open, the same limits and plan.

Keys

Make a key in Settings → API keys. It is shown once. Send it on every call:

Authorization: Bearer sfk_…

A read-only key lists and reads decks, reads generations, lists webhooks and downloads finished exports. A read and write key can also start generations (which count against your plan and may cost money), upload source files, make exports, and subscribe or end webhooks. Each key may make 600 calls an hour. A missing, wrong or revoked key gets 401; a read-only key asking for any of those gets 403. Errors are JSON: {"error": "what went wrong"}.

Decks

GET /api/v1/decks: your decks and your teams' decks, most recently updated first (?limit= up to 100, ?offset=, ?q= to search titles).

curl -H "Authorization: Bearer $KEY" https://claravo.ai/api/v1/decks

GET /api/v1/decks/{id}: one deck, with its whole document (slides, elements, notes, sources). A deck you cannot open is 404.

Exports

POST /api/v1/decks/{id}/exports with {"format": "pptx"} (or pdf, png, markdown, notes; a document takes docx, pdf, png or markdown; both take numbers-pdf and numbers-xlsx, the report of every number and where it was found, and svg, a zip with one SVG file per chart and diagram, and pptx takes "numberTrail": true to add each number's source to the speaker notes). It answers once the file is made and has passed its check, with a download address; fetch that with the same key.

curl -X POST -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"format":"pptx"}' https://claravo.ai/api/v1/decks/DECK_ID/exports
curl -H "Authorization: Bearer $KEY" -o deck.pptx https://claravo.ai/api/v1/exports/EXPORT_ID

Generations

POST /api/v1/generations (write key) with the same settings as the create page. Only prompt is required; others include slideCount, audience, tone, format (deck; document for a written report of up to 20 sections, with docPreset a4 or letter; or carousel, up to 20 cards, with cardShape 1:1, 4:5 or 9:16), narrative, interview, language (en, es, fr, de, pt, it, nl), research and researchDepth (standard or deep; on some plans deep research counts as more than one creation, or is not included: 403 or 402 with the reason), and quality (standard, or premium where the site offers it: written by a more capable model, and on some plans it counts as more than one creation or is not included, with the same answers). It answers at once with an id; the deck is made in the background, straight through (reviewing the outline first is only in the app). While AI is switched off on the site (by its operator, or because the day's AI budget is used), it answers 503 with the reason.

curl -X POST -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"prompt":"Quarterly review for the board","slideCount":8}' https://claravo.ai/api/v1/generations

GET /api/v1/generations/{id}: status (queued, running, succeeded, failed, cancelled), the stages, and deckId once the deck is saved. Poll every few seconds; a deck takes about two minutes. Each stage's status is pending, running, done, failed, skipped (left out on purpose, with the reason in detail) or not-run (never reached, because the run failed, was cancelled or was stopped first). Runs from before 3 October 2026 may show skipped for a stage that was never reached.

To build from your own files, upload each one first: POST /api/v1/uploads (write key) with the file as multipart/form-data in a field named file (PDF, Word, PowerPoint, Excel, CSV, text or Markdown; the same size limit and hourly count as uploads in the app). It answers 201 with the file's id and whether it could be read; pass the ids as sourceFileIds when you start a generation. A scanned PDF is read in the background; a generation started before it is ready gets 409.

curl -X POST -H "Authorization: Bearer $KEY" -F "file=@brief.docx" https://claravo.ai/api/v1/uploads
curl -X POST -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"prompt":"Quarterly review for the board","sourceFileIds":["UPLOAD_ID"]}' https://claravo.ai/api/v1/generations

Check the numbers in a text

POST /api/v1/checks takes multipart/form-data with the text in a field named text (up to 50,000 characters) and up to ten files named file (40MB together). Every number in the text is looked for in the files, and the answer says which were found (with the passage), which to check, and which are in none of them, and which files could be read. No AI runs and nothing sent is kept. A read key is enough. Each check counts towards your plan’s checks for the month, and a summary (the counts, no text) is kept in your check history.

curl -X POST -H "Authorization: Bearer $KEY" \
  -F "text=Revenue rose 12% to $4.2M this quarter." \
  -F "file=@q3-results.xlsx" https://claravo.ai/api/v1/checks

POST /api/v1/figures/check takes JSON { "text": "…" } and says where the text quotes one of your company numbers (your own and your teams'), and whether it says the same.

Webhooks (Zapier, Make and your own programs)

POST /api/v1/hooks (read and write key) with {"event": "generation.finished", "targetUrl": "https://…"} (or export.ready) tells that address when a generation you started ends (succeeded, failed or cancelled) or an export you made is ready. The answer holds the subscription's id and its signing secret, shown once. GET /api/v1/hooks lists them with each one's latest delivery (its state, tries, answer and any error), DELETE /api/v1/hooks/{id} ends one, and GET /api/v1/hooks/samples/{event} shows your latest real events in the same shape. At most 20 per account; the address must be https on the public internet. Revoking the key that made a subscription ends it.

curl -X POST -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"event":"export.ready","targetUrl":"https://example.com/claravo"}' https://claravo.ai/api/v1/hooks

Each event is one POST of JSON: event, id, occurredAt and data (ids, status, title, and the deck and download addresses, never the deck's content). It carries X-Claravo-Signature: t=…,v1=…: the hex HMAC-SHA256, with your secret, of the time, a full stop and the body; check it and that the time is recent. Answer with any 2xx. A timeout, a network error, a 429 or a 5xx is tried again after 1, 5 and 30 minutes and 2 hours, then given up; any other answer is final, and 410 Gone ends the subscription. Redirects are not followed. Events can arrive up to about 15 seconds after they happen.

Zapier and Make apps that use these are in the repository (integrations/) and are not yet listed in those services' directories.

Use Claravo from an AI assistant (MCP)

https://claravo.ai/api/mcp is a Model Context Protocol server (Streamable HTTP). An assistant connected to it can list and read your decks (list_decks, get_deck) and follow generations (get_generation), and, with a read and write key, export them (export_deck) and make new ones (start_generation). It can also check the numbers in its own draft before giving it to you: list_uploads lists your files, and check_text looks every number in a text up in them and in your company numbers.A read-only key is not offered the write tools. It uses the same API keys, limits and access rules as the calls above; each message counts as one call.

In Claude Code:

claude mcp add --transport http claravo https://claravo.ai/api/mcp --header "Authorization: Bearer sfk_…"

In a project's .mcp.json for Claude Code, and in other clients whose JSON settings take a remote server with headers:

{
  "mcpServers": {
    "claravo": {
      "type": "http",
      "url": "https://claravo.ai/api/mcp",
      "headers": { "Authorization": "Bearer sfk_…" }
    }
  }
}

Clients that only connect through an OAuth sign-in (such as custom connectors added in a web chat app) cannot connect yet; such a client may try to sign in and fail. Claude Desktop's settings file takes only local servers, so it needs a bridge program to reach this one. Markdown and speaker-notes exports come back as text; other files as a download address that needs the same key. Keep the key private: anyone with it acts as you.

Not in the API yet

Editing decks, reviewing an outline before it is built, teams and comments. Use the app for those.