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 whether your account is switched on.

Verify your key (spends nothing)

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

A 401 means the key is wrong or revoked. A 503 means we are unavailable — retry, do not re-mint. A 403means the key is valid, and the body's reason splits into two different things — see Authentication for the full picture:

reason: "not_enrolled" — the key is fine. The API and MCP server are switched on for everyone, and your keys start working the moment your account is in, with nothing to redo. If it persists beyond a day, contact support with the requestId from the response.
reason: "insufficient_scope" or "unrecognized_scope" — this is about the key, not your account. Widen its scopes, or re-issue it with the scopes the response names.

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 lands within 10–35 minutes — budget for that, not for a coffee break. Read Jobs & polling before you write the loop — there is one status that means the opposite of what it looks like.