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.