authentication

The spirby api authenticates every request with a bearer api key. Keys carry an organization id and a scope; there is no X-Organization-Id header to set on the public surface.

mint a key

1. Sign in at <your-subdomain>.spirby.com/app.
2. Go to settings → api keys.
3. Click new key, pick a label and a scope, and copy the secret.

The secret starts with spk_ and is shown once. Spirby stores only a hashed equivalent; if you lose the secret, mint a new key and revoke the old one.

sending the key

Set the Authorization header on every request:

Authorization: Bearer spk_<random>

Anything else (query param, cookie, body field) is rejected.

scopes

Two scopes; pick the smallest that fits the integration.

scope	reads	writes	typical use
read	yes	no	mirror posts and votes into a dashboard
read:write	yes	yes	bot that creates posts or marks status

A read key calling a write endpoint returns 403 ERR_SCOPE_INSUFFICIENT. A read:write key satisfies any endpoint.

curl https://api.spirby.com/v1/boards \
  -H "Authorization: Bearer spk_<your_key>"

rate limits

Every key has a per-key budget. Spirby returns the current state on every response — success or failure — so a polite client can back off before getting a 429.

header	meaning
X-RateLimit-Limit	total requests allowed in the current window
X-RateLimit-Remaining	requests still available in the current window
X-RateLimit-Reset	unix seconds at which the window resets
Retry-After	seconds to wait before retrying (only set on 429)

When the budget is exhausted you get:

HTTP/1.1 429 Too Many Requests
Retry-After: 18
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1731000018

{ "error": { "code": "ERR_RATE_LIMITED", "message": "rate limit exceeded" } }

The default budget is 1000 requests per hour per key. Need more? open a ticket and tell us which integration is being throttled.

error envelope

All non-2xx responses share one shape. details is present only when the server has structured information to add (e.g. zod issues on 422).

{
  "error": {
    "code": "ERR_VALIDATION",
    "message": "validation failed",
    "details": { "issues": [ ... ] }
  }
}

See overview → stable error codes for the full list.

verify the setup

Once you have a key, list your boards:

curl -i https://api.spirby.com/v1/boards \
  -H "Authorization: Bearer spk_<your_key>"

A 200 with a data array means the key works. From here, head to quickstart for ten copy-paste curls covering the most common flows.