Rate limits
Token-bucket limits protect the public capture endpoint and AI features. Everything else is unmetered today.
Rate-limited surfaces use a token bucket: you get a burst capacity that refills continuously. When the bucket is empty the API returns 429 with a Retry-After header (seconds).
| Surface | Scope | Burst | Refill |
|---|---|---|---|
POST /capture/{token} (valid token) | per capture hook | 20 requests | 1 request / 2s |
POST /capture/{token} (unknown token) | per client IP | 10 requests | 1 request / 5s |
AI assist (…/ai/suggest, …/ai/summarize) | per organization | 30 requests | ~180 / hour |
AI assist responses use code: "RATE_LIMITED" in the error envelope.
Handling 429s
Respect Retry-After and back off:
const res = await fetch(url, options);
if (res.status === 429) {
const wait = Number(res.headers.get("Retry-After") ?? "5");
await new Promise((r) => setTimeout(r, wait * 1000));
// retry once
}Other endpoints are not rate-limited today, but don't design an integration that hammers them — limits may be added, and the same 429 + Retry-After contract will apply.