The Kaptr API

Get started

1. In Kaptr, open Settings → API and create a key. Name it after the tool that will use it.
2. Copy the key: it is shown only once.
3. Call the API at https://kaptr.me/api/v1 with the key in the Authorization header.

curl https://kaptr.me/api/v1/me \
  -H "Authorization: Bearer kaptr_…"

Every answer is JSON. Lists are paginated: pass limit (1–100) and the nextCursor of the previous page as cursor.

Keys and access

A key belongs to your account and acts as it: it sees your dashboards, your team's dashboards and the ones shared with you, with the same rights as in the app (a team viewer only reads, only a dashboard's owner shares it). Keep it like a password, and revoke it in Settings → API if it leaks: the next request made with it is refused.

An account can hold up to 10 keys. They work while the account has Business.

Limits

Each key may send, per minute, 60 reads, 30 changes and 5 AI actions; each account 50,000 requests per month, and up to 3 AI jobs at a time. Every answer says where you stand:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1791380460

Past a limit the API answers 429 with a Retry-After header (in seconds). AI actions also use AI credits, exactly as in the app: Kaptr Fast, Vision and Agent cost their published price per generation, a cloud refresh 1 credit, Ask AI its usual price. Your plan's limits apply too (dashboards per account, snapshots per dashboard).

Errors

{
  "error": {
    "code": "scope_required",
    "message": "This key is read-only. Create a read and write key in Kaptr → Settings → API.",
    "requestId": "req_3f2a9c1d…"
  }
}

Retries without duplicates. Creations accept an Idempotency-Key header (8–100 characters): the same request sent again with the same key returns the first result instead of doing it twice.

Dashboards

curl -X POST https://kaptr.me/api/v1/dashboards \
  -H "Authorization: Bearer kaptr_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: weekly-report-2026-41" \
  -d '{"title": "Weekly market report"}'

Snapshots

Kaptr AI

AI actions run as jobs: the request answers at once with the job (202), and you follow it with GET /jobs/{id} until its status is completed or failed. Add ?wait=30 to either request to let the API wait for the end (up to 50 seconds).

curl -X POST "https://kaptr.me/api/v1/dashboards/DASHBOARD_ID/generations?wait=45" \
  -H "Authorization: Bearer kaptr_…" \
  -H "Content-Type: application/json" \
  -d '{"model": "vision", "prompt": "Current S&P 500 heatmap"}'

Credits are reserved when the job starts and charged only for a usable result. A generation that ends while its dashboard is full waits in needs_space: free some room, then read the job again to add its snapshots.

Team

OpenAPI

The full description of every request and answer is at https://kaptr.me/api/v1/openapi.json (OpenAPI 3.1): import it in Postman, Insomnia or your code generator. A question, or an endpoint you are missing? Tell us.