Reference
API Endpoints
Every DuckViz app endpoint with method, auth, SSE, rate limit, and credit cost.
Flat reference for every endpoint on app.duckviz.com. Use this when:
- Building a server proxy with
@duckviz/sdk
- Auditing which calls your PAT can reach
- Budgeting credit cost for a workflow
All endpoints expect application/json POST bodies (≤ 1 MB), except GET where noted. SSE routes return text/event-stream. See Server Proxy Setup for wiring.
| Column | Meaning |
|---|
| Bearer | Authorization: Bearer dvz_live_… accepted |
| Cookie | Session cookie accepted |
| Cookie-only | PAT is rejected — see bearer-first precedence |
| Endpoint | Method | SSE | Auth | Rate | Credits (Std) |
|---|
/api/widget-flow/fast-recommend | POST | ✓ | Bearer / Cookie | ~60/min | 3 (0 on cache hit) |
/api/widget-flow/classify | POST | ✓ | Bearer / Cookie | ~60/min | 1 |
/api/widget-flow/suggest-viz | POST | ✓ | Bearer / Cookie | ~60/min | 2 |
/api/widget-flow/generate | POST | ✓ | Bearer / Cookie | ~30/min | 5 |
/api/widget-flow/fix-query | POST | — | Bearer / Cookie | ~60/min | 1 |
/api/widget-flow/suggest-prompts | POST | — | Bearer / Cookie | ~60/min | 1 |
/api/widget-flow/clarify | POST | — | Bearer / Cookie | ~30/min | 0 |
/api/widget-flow/precompute | POST | — | Bearer / Cookie | Own bucket | 0 |
| Endpoint | Method | SSE | Auth | Credits (Std) |
|---|
/api/generate-report-sections | POST | ✓ | Bearer / Cookie | 5 |
/api/modify-report-section | POST | — | Bearer / Cookie | 2 |
/api/generate-deck-slides | POST | ✓ | Bearer / Cookie | 3 |
/api/modify-deck-slides | POST | — | Bearer / Cookie | 2 |
| Endpoint | Method | SSE | Auth | Credits (Std) |
|---|
/api/detect-log-format | POST | — | Bearer / Cookie | 1 |
| Endpoint | Method | SSE | Auth | Credits (Std) |
|---|
/api/query-from-prompt | POST | — | Bearer / Cookie | 1 |
| Endpoint | Method | SSE | Auth | Credits |
|---|
/api/credits/balance | GET | — | Bearer / Cookie | 0 |
/api/usage | GET | — | Bearer / Cookie | 0 |
Stolen PATs must not mint tokens or move money. These routes reject bearer:
| Endpoint | Method | Purpose |
|---|
/api/tokens | GET, POST | List / mint PATs |
/api/tokens/:id | DELETE | Revoke PAT |
/api/referrals | GET | List referrals |
/api/referrals/invite | POST | Send invite (10 / 24h) |
/api/checkout | POST | Paddle transaction / hosted-checkout session |
/api/paddle/webhook | POST | Paddle webhook (server-to-server, HMAC-verified) |
/api/custom-log-formats | GET, POST | List / create custom format |
/api/custom-log-formats/:id | PUT, DELETE | Update / delete custom format |
/api/feedback | POST | In-app feedback submission |
/api/auth/resend-confirmation | POST | Re-send confirmation email |
Clients parse the SSE stream as data: {"event":"<name>","data":...}\n\n. Errors emit a final error event; the stream then closes.
| Event | Meaning |
|---|
thinking | LLM is generating — only fires when the fast path misses cache |
domain | Detected data domain (e.g. "Sales & Revenue") |
fast-result | Viz type + SQL for a single widget — main payload |
viz_suggestion | Viz type picked — only when falling back to the 3-step path |
widget | Enriched widget payload (query + chart config) ready to render |
done | Stream closed |
error | Recoverable failure — the client should fall back |
| Event | Meaning |
|---|
section-start | One report section has begun streaming |
section-complete | That section's content is finalized |
section-error | One section failed; others continue |
done | All sections processed |
error | Stream-level failure |
| Event | Meaning |
|---|
slide-start | One deck slide has begun streaming |
slide-complete | That slide is finalized |
slide-error | One slide failed; others continue |
done | All slides processed |
error | Stream-level failure |
Minimal set: a single payload event named after the stage, plus done / error. Used in the slow-path fallback when fast-recommend can't satisfy the request.
Every base cost above is Standard tier. Premium multiplies by PREMIUM_CREDIT_MULTIPLIER = 5 — so fast-recommend becomes 15, report sections 25, etc. See Billing & Plans for the mechanics, and Credits for the full base-rate table with rationale.
Source of truth: apps/app/lib/auth/credits.ts — this reference updates whenever that file changes. If you find a mismatch, file an issue.
| Header / limit | Value |
|---|
| Max request body | 1 MB |
| Rate-limit bucket | Per-user KV sliding window |
| SSE keepalive | Comment every ~15 s (: keep-alive\n\n) |
| Security headers | X-Frame-Options: DENY · X-Content-Type-Options: nosniff · Referrer-Policy: strict-origin-when-cross-origin · HSTS · COOP: same-origin-allow-popups |
DuckViz