API

The Capsules API

Call Capsules from your own code with a workspace API key. The API is in beta: the surface is growing and may change. If you want an AI agent to work with Capsules, connect it over MCP instead, which needs no code.

API keys

Create a key in Settings, API Keys, on plans with API access. The full key is shown once. A key acts in the workspace it was created in, as the person who created it, so treat it like a password and revoke it when you no longer need it.

Send it in a header:

Request
curl https://api.staging.capsules.ink/api/v2/me \
  -H "x-api-key: cap_your_api_key"

Authorization: Bearer cap_… works too. Never put a key in a URL or a request body.

Reference

New endpoints live under /api/v2 and are described by an OpenAPI 3.1 document. Every error has the same shape: { error, details? }.

Limits and credits

  • Requests are rate limited. A 429 response means wait a minute, then retry.
  • Generation spends the workspace's credits at the same prices as the editor. Failed generations are refunded automatically.
  • Don't retry a request that spends credits after a timeout. Read the capsule first to see whether it landed.