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: 
{
  "items": [],
  "total": 0,
  "limit": 25,
  "offset": 0
}
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: 
{
  "resource": "issues",
  "items": [],
  "total": 0,
  "limit": 25,
  "offset": 0,
  "nextOffset": null,
  "truncated": false,
  "hint": null
}

​
Pagination

List endpoints support:
Query paramMeaning
limitNumber of results, default 25, max 100
offsetOffset into the result set
Example: 
curl -H "Authorization: Bearer $ATOLL_API_KEY" \
  "https://atollhq.com/api/orgs/$ATOLL_ORG_ID/issues?limit=100&offset=100"

​
Error format

Most errors return: 
{
  "error": "message"
}

​
Common status codes

StatusMeaning
400Invalid request or validation error
401Missing or invalid authentication
402Billing plan limit reached
403Authenticated but not allowed
404Resource not found or not visible
409Conflict, such as duplicate dependency
429Rate limited
500Unexpected server error

​
Plan limit errors

Creation endpoints can return 402: 
{
  "error": "Plan limit reached",
  "code": "PLAN_LIMIT_REACHED",
  "resource": "activeProjects",
  "plan": "free",
  "limit": 2,
  "usage": 2
}
resource can be:
  • humans
  • agents
  • activeProjects
  • activeIssues

​
Deletion permissions

Permanent task delete requires owner/admin access: 
DELETE /api/orgs/{orgId}/issues/{issueId}
For most workflows, use archive instead: 
POST /api/orgs/{orgId}/issues/{issueId}/archive
Reverse it with: 
DELETE /api/orgs/{orgId}/issues/{issueId}/archive