Skip to main content
Atoll returns JSON for API responses.

Success responses

Successful create requests usually return 201. Reads and updates usually return 200. List responses include pagination fields:
REST list endpoints keep their legacy resource-key shape by default. Main list endpoints also support ?shape=envelope (alias: ?response_shape=cli) for the same agent-friendly envelope used by CLI JSON list output:

Pagination

List endpoints support: Example:

Error format

Most errors return:
Missing authentication on a shared guarded route returns:
Unknown /api/* paths return:
OAuth profile selection uses stable machine-readable error values: These errors occur before the requested business handler reads or changes its resource. invalid_profile deliberately does not reveal whether the rejected reference exists under another connection. The POST initiative issue, initiative milestone, and initiative-target issue link routes normalize accepted identifiers before writing the relationship. They return these stable messages when resolution fails: Missing request fields use the route-specific issue_id is required or milestone_id is required message. Successful writes store the canonical UUID, even when the request used a number, prefix, or milestone name.

Common status codes

Directly requested project-bound resources, including issues and their child resources, milestones, board columns, status updates, PR links, and issue activity, use 404 to conceal a missing, wrong-organization, wrong-parent, or unreadable resource. A readable project or resource with insufficient write access returns 403; collection reads can omit unreadable linked resources. Organization-level role failures may also return 403.

Plan limit errors

Creation endpoints can return 402:
resource can be:
  • humans
  • agents
  • activeProjects
  • activeIssues

Deletion permissions

Permanent task delete requires owner/admin access:
For most workflows, use archive instead:
Reverse it with:
Projects, goals, KPIs and initiatives accept q for case-insensitive literal substring matching of the display name/title, q_exact=true for the complete name, and limit/offset for server-side pagination. Defaults in bounded mode are 25 results, maximum 100, and offset 0. Filtering and authorization precede pagination; offsets beyond matching results return an empty page with the exact total. KPI pages include current calculated values. Use shape=envelope (or response_shape=cli) for resource, items, total, limit, offset, nextOffset, truncated and hint. Supplying a search or pagination parameter also selects bounded retrieval. Calls without these parameters retain their legacy resource-key response and full-list behavior. Members add member_id=<UUID> and q_exact=true in bounded directory mode. Identity filtering uses the same collaborator visibility rules and safe fields as name search; it does not grant access or return credentials or account email. Members and initiatives also accept scope=accessible_projects for a bounded union under the current actor. The server derives project IDs; callers cannot supply ID arrays. Guests see only accessible project-linked initiatives and eligible collaborators. Existing member/admin projectless initiative rights remain. Empty project access gives guests an empty page. Unknown scope or scope combined with an explicit project returns 400. Explicit project scope remains project_id for initiatives and projectId for members. Full issue lists resolve authorized human identifiers such as AH-123, ATOLL-123, #123 or a number before loose title/description matching. They also accept q_exact=true for the full title. The exact flag is rejected with 400 for compact view=board/view=list; existing compact search stays unchanged. The existing issue filters and actor/project authorization still apply. CLI list commands for projects, goals, KPIs, initiatives and members use --search, --exact, --limit and --offset; issue list uses --q with --exact. Member list also supports --member-id. These filters are evaluated by the API. Existing public/private MCP list tools expose q, q_exact, limit and offset; atoll_list_members adds member_id. Member and initiative lists expose --accessible-projects in the CLI and scope=accessible_projects in MCP. The initiative flag suppresses a configured default project and cannot combine with --project or --org-wide. Normal MCP goal/KPI/initiative calls without query, exact, paging or scope options retain legacy full-list responses. Composer search uses a constant number of bounded list calls per profile and entity kind, independent of the number of accessible projects.

Actor recommendation pages

Actor recommendation reads return safe error and code strings. Invalid query, actor cursor scope, or signature returns 400 WORK_RECOMMENDATIONS_INPUT_INVALID; a cursor older than 15 minutes returns 400 WORK_RECOMMENDATIONS_CURSOR_EXPIRED. Changed authorization, lifecycle, assignment, execution, or ranking evidence returns 409 WORK_RECOMMENDATIONS_CURSOR_STALE. Retry without a cursor for a fresh snapshot. Missing and forbidden targets/projects both return 404. A complete read that exceeds any evidence bound returns 422 WORK_RECOMMENDATIONS_EVIDENCE_LIMIT, with no ranked prefix. Read/validation failures return safe 500 codes. The existing project-only endpoint retains its unsigned navigation cursor behavior.

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 429 rate_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.