Success responses
Successful create requests usually return201. Reads and updates usually return 200.
List responses include pagination fields:
?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:/api/* paths return:
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.
Initiative link resolution errors
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 return402:
resource can be:
humansagentsactiveProjectsactiveIssues
Deletion permissions
Permanent task delete requires owner/admin access:Bounded collection search
Projects, goals, KPIs and initiatives acceptq 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 safeerror 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 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.
