Quickstart

What it costs before you start, then a first authenticated call that spends nothing.

What this costs, before you write any code

A new account gets a small welcome grant of credits. It is deliberately less than one deck costs.
A deck costs a few hundred credits — less if you subscribe. Every one of these numbers is tuned at runtime, so the only trustworthy source is your own Settings → API & MCP, which shows your live balance as a number of decks. Do not hard-code a price from this page.
The credits buy the generation. What comes back first is a watermarked preview; removing the watermark and downloading a clean, editable .pptx is a separate one-off purchase, or included with Pro. So a first deck costs credits and an unlock unless you subscribe.
There is no test mode. Clerk issues keys with ak_test_ and ak_live_ prefixes, but AskDeck treats them identically: an ak_test_ key spends real credits. There is no sandbox key. We would rather say that here than have you find out from an invoice.

1. Mint a key

Sign in and open Settings → API & MCP. The secret is shown once, at creation. We cannot show it again — if you lose it, revoke it and mint another.

2. Prove the whole chain, spending nothing

This is a read. It costs no credits, and it exercises every step that can go wrong: the key, our verification of it with Clerk, the principal we resolve from it, and the access list.

Verify your key (spends nothing)

curl -s "https://api.askdeck.ai/v1/decks?limit=1" \
  -H "Authorization: Bearer $ASKDECK_API_KEY"

A 401 means the key is wrong or revoked. A 403 means the key is fine and your account is not on the preview access list yet. A 503 means we are unavailable — retry, do not re-mint.

3. Create a deck

This one spends. It returns immediately with a taskId; the deck is not ready yet.

Create

curl -s -X POST https://api.askdeck.ai/v1/decks \
  -H "Authorization: Bearer $ASKDECK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "core_message": "Q3 revenue grew 22% on enterprise renewals",
        "audience": "our board",
        "title": "Q3 revenue review",
        "slide_count": 10,
        "expected_credits": 300
      }'

expected_credits is the price you were quoted. If the live price has moved, the call fails with 409 price_drift instead of charging you a number you did not agree to. Quote first; never omit it to make the 409 go away.

The body is strict: an unknown field is a 422, not a warning. The fields are deck_class, audience, core_message, title, slide_count, notes, context, material_ids, output_language, additional_languages, confirm_slide_surcharge and expected_credits. The full schema is in the reference.

4. Poll

Status

curl -s https://api.askdeck.ai/v1/decks/$TASK_ID/status \
  -H "Authorization: Bearer $ASKDECK_API_KEY"

Poll every 5 seconds. A deck typically finishes inside three minutes. Read Jobs & polling before you write the loop — there is one status that means the opposite of what it looks like.