Skip to main content

Brief-to-deck (PDF intake)

Problem: A user uploads a brief PDF to your app. You want to produce a branded pitch deck from it and return a PPTX download URL.

Primitives

  • POST /v1/uploads — upload the PDF (multipart)
  • POST /v1/tasks with attachments: [{file_id, role: "source"}] + brand_kit_id + number_of_slides
  • Webhook OR polling to detect completion
  • POST /v1/canvases/{id}/export?format=pptx — synchronous export

TypeScript (Node 20+)

Webhook handler (abbreviated — full handler in webhook-receiver.md):

Python (FastAPI + httpx)

Webhook handler does the export:

Gotchas

  • idempotency_key encoding. Using {user_id}:{file_id} means re-uploading the same PDF for the same user hits the same task (desirable — idempotent, no wasted compute). If you want a fresh task each time, include a timestamp.
  • Brief → role: "source". The agent extracts content. Passing it as reference would make the deck mimic the PDF’s formatting — not what you want.
  • number_of_slides is a hint, not a hard cap. If the brief is thin, the agent may produce fewer; if it’s rich, marginally more.
  • Export is synchronous. No polling the export. One POST, one URL.
  • Signed PPTX URL expires after 7 days. Either surface it directly to the user (they’ll click within minutes usually) or download + re-host yourself.
  • callback_url requires API-key auth. This recipe runs server-side so that’s fine. An OAuth / MCP caller can’t set callback_url — they’d have to poll.
  • If brand_kit_id is null (empty team), the design task still runs but without brand styling — or you can error out. Decide based on UX: for internal tools, off-brand is fine; for customer-facing, force the user to set up a brand kit first.

See also