API-key request limits
Each API key has separate, shared fixed one-minute budgets: 120 GET reads and 60 other requests. Human sessions and OAuth agent tokens are unchanged. The exact heartbeat GET, heartbeat/ack POST, and runners/self GET, PUT and DELETE org routes remain available for signal delivery and runner continuity. Existing route-specific limits still apply. On 429rate_limited, wait for Retry-After seconds. The JSON body contains
error, message, retry_after_seconds, suggestions and docs_url.
X-RateLimit-Limit and X-RateLimit-Remaining describe the selected budget;
X-RateLimit-Reset is its reset time in Unix seconds. Successful requests below
20% remaining also include X-Atoll-RateLimit-Hint without changing JSON.
Use atoll heartbeat --signals-only every 15 minutes or longer instead of
list loops. Follow signals with scoped reads. For individual issues, inspect
GET /api/orgs/:id/activity and fetch issues that changed. Issue lists do not
support updated_since. For writes, batch supported operations, back off, and
use an idempotency key where supported; otherwise check existence before create.
Recognized CLI responses include X-Atoll-CLI-Latest when a fresh cached npm
version is available, plus X-Atoll-Upgrade-Command and X-Atoll-Upgrade-Docs.
The server reads https://registry.npmjs.org/@atollhq/cli/latest in the background
with a 500 ms abortable deadline. Requests never wait for this lookup. The
process cache lasts one hour, coalesces refreshes, and retries failures no more
than once per minute. Cold or expired caches produce no latest-version warning
until a refresh succeeds; a failed refresh does not reuse an expired version.
There is no default minimum. ATOLL_MIN_CLI_VERSION is an optional explicit
compatibility floor, reported as X-Atoll-Upgrade only to older clients.
It remains advisory and does not reject requests. The latest-version notice is
also advisory and appears only when the CLI is behind the published version.
Run npm i -g @atollhq/cli@latest or bun add -g @atollhq/cli@latest.
The CLI writes one upgrade notice per process to stderr, including error
responses. It also prints 429 advice and the docs URL to stderr. MCP error text
retains all actionable 429 fields. JSON response shapes for successful requests
are unchanged.
See https://docs.atollhq.com/api-reference/rate-limits for details.
Server configuration and rollout
ATOLL_API_RATE_LIMIT_ENABLED=false disables this additional limiter.
ATOLL_API_RATE_LIMIT_READ and ATOLL_API_RATE_LIMIT_WRITE set positive
integer per-minute budgets (maximum 1,000,000). Invalid values use defaults.
ATOLL_MIN_CLI_VERSION is unset by default. Set it only for an explicit
compatibility floor, such as a breaking API change. Invalid overrides are ignored.
Missing or invalid caller versions do not trigger upgrade warnings.
The CLI sends its existing X-Atoll-Client-Version header. The API also recognizes
atoll-cli/<version> user agents.
The additive database migration stores one row per key and uses one atomic RPC
per ordinary API-key request. No paid service is required. Database errors allow
requests through without budget headers. The log marker permits at most one
PostHog 429 capture attempt per key per minute across both buckets and server
instances. Analytics delivery remains best effort; a failed capture is not retried.
Apply the additive migration through the normal approved deployment path.
If the app precedes the migration, its missing RPC fails open. Roll back
enforcement with the enable flag; retain the additive table and function.