Authentication & concepts

Authentication

All endpoints require an API key. Free accounts get a bounded one-time trial; Pro and Developer both get a real recurring monthly volume (Dashboard → Account → API & MCP; the key is shown once, at creation).

Pass your key in every request header:

x-api-key: capci_your_api_key_here

Posts, diagrams, carousels and animations draw from your plan's generation volume, no per-call charge: 50 lifetime on Free (shared with the web app), 200/mo on Pro, 900/mo on Developer (resets each billing period). Logo creation is the one metered exception on every plan (see /logo in the Brand & assets reference): your first logo is free, every one after draws from your account's credit balance.

Core concepts

Brand resolution & `unbranded`

Every image carries a small identity badge (name + logo, top-right) unless you opt out. Resolution order:

Your saved brand (POST /brand, or a per-call brand override) always wins.
If you've never set a brand, the badge defaults to Capci's own mark, never a blank placeholder.
Pass unbranded: true on any generation call, such as /posts, /diagrams, or /refine, to strip the badge entirely for that one generation. Brand colors are kept so output stays on-palette but anonymous. This never touches your saved profile. (The MCP server exposes the same flag on its create_post / create_diagram / refine_diagram tools; see MCP server.)
Diagrams are the exception, and default to unbranded. A diagram generated over the API or MCP is an asset you drop into someone else's README, deck, or docs, so it carries no badge unless you ask for one: pass unbranded: false per call, or turn Brand mark on diagrams on in Dashboard → Account → API & MCP defaults to brand every diagram. Posts, charts and carousels are unaffected and stay branded.

Note: the API surface never stamps a "Made with Capci" attribution watermark on your output, regardless of your dashboard watermark setting; that toggle only affects the Studio web app.

Diagram style defaults (separate from your brand, which applies everywhere)

Set fallback theme / size / nodeStyle / transparent / brand-mark values once in Dashboard → Account → API & MCP defaults. Any /api/v1/diagrams or /refine call that omits one of those fields falls back to your saved default, then to the system default (light / auto / boxed / opaque / unbranded); pass the field explicitly on any call to override it just once. auto is an adaptive frame rather than a fixed ratio: each diagram is rendered vertical (4:5) or landscape (16:9), whichever its own shape actually fits, and the response reports the concrete size chosen. This style-default fallback is diagram-specific; /posts and /chart use the defaults listed in their own tables instead. Your brand (name, logo, colors) is a separate setting from this and always applies to every endpoint. See Brand resolution above.

Rate limits

60 requests / minute per API key on anything that creates or edits content (/posts, /diagrams, /chart, /carousel, /animate, /batch, /logo, etc.). Polling GET /jobs/{id} or GET /jobs/batch/{batchId} for an async job doesn't count against this, poll every 2-3 seconds freely.

Every response carries standard RateLimit-* headers; a 429 means back off and retry after RateLimit-Reset seconds.

Not available via the API

/posts, /chart, and /carousel generations aren't stored by Capci, so save the response yourself if you need it later, since there's no endpoint to list past generations. Diagrams are the one exception: they persist permanently under their id so you can refine/export them later, but there's still no "list all my diagrams" call. Track ids on your own end if you need that.