# Atoll API Field Reference ## Table of Contents - [Task Fields](#task-fields) - [Goal Fields](#goal-fields) - [KPI Fields](#kpi-fields) - [KPI Snapshots](#kpi-snapshots) - [Initiative Fields](#initiative-fields) - [Automation Rule Fields](#automation-rule-fields) - [Custom View Fields](#custom-view-fields) - [Webhook Fields](#webhook-fields) - [Heartbeat Response](#heartbeat-response) - [Analytics Response](#analytics-response) - [Plan Limit Errors](#plan-limit-errors) - [Enums](#enums) --- ## Task Fields Request bodies accept **camelCase** (`assigneeId`, `projectId`). Snake_case also accepted for backward compatibility. Responses always use snake_case. ```json { "title": "Fix login bug", "description": "Markdown supported", "status": "todo", "priority": 1, "assigneeId": "member-uuid", "assigneeIds": ["member-uuid-1", "member-uuid-2"], "projectId": "project-uuid", "milestoneId": "milestone-uuid", "teamId": "team-uuid", "startDate": "2026-03-01", "dueDate": "2026-04-01", "recurrenceType": "weekly", "recurrenceInterval": 1, "labelIds": ["label-uuid-1", "label-uuid-2"] } ``` All fields work on both POST (create) and PATCH (update). - **Multiple assignees**: Use `assigneeIds` (array). Legacy `assigneeId` (single) still works. Responses include `assignees` array with `id`, `display_name`, `type`, `avatar_url`. - **Start date**: Sets when work begins. Combined with `dueDate`, defines the Gantt time span. - **Recurring tasks**: Set `recurrenceType` + optional `recurrenceInterval` (default 1). When marked `done`, a new instance is auto-created. Response includes `recurrence_next_date`. - **Archived tasks**: Have `archived_at` timestamp. Excluded by default; pass `includeArchived=true`. - **GET detail** returns enriched data: `milestone`, `assignee`, `assignees`, `sub_tasks`, `issue_labels`, `isBlocked`. **Bulk create** (`POST /issues/bulk`): ```json { "issues": [{ "title": "Task 1", "status": "todo", "priority": 1, "projectId": "..." }] } ``` Returns `{ issues: [...], count: N }` (201). Max 50 per request. ## Plan Limit Errors Creation endpoints may return `402` when an org reaches its billing plan limit: ```json { "error": "Plan limit reached", "code": "PLAN_LIMIT_REACHED", "resource": "activeProjects", "plan": "free", "limit": 2, "usage": 2 } ``` `resource` is one of `humans`, `agents`, `activeProjects`, or `activeIssues`. ## Goal Fields ```json { "title": "Reach 100 paying customers by Q2", "description": "Our primary growth objective", "owner_id": "member-uuid", "status": "active", "target_date": "2026-06-30" } ``` ## KPI Fields ```json { "name": "paying_customers", "description": "Total active paying customers", "goal_id": "goal-uuid", "unit": "count", "unit_label": "customers", "target_value": 100, "target_direction": "increase", "source_type": "manual", "stale_after_hours": 168 } ``` ## KPI Snapshots ```json { "value": 34, "source": "agent", "attribution_note": "Checked Stripe dashboard", "attributed_to_initiative_id": "initiative-uuid", "attributed_to_issue_id": "issue-uuid" } ``` Recording a snapshot auto-updates the KPI's `current_value`. ## Initiative Fields ```json { "title": "Launch self-serve onboarding flow", "description": "Reduce friction for new signups", "goal_id": "goal-uuid", "owner_id": "member-uuid", "status": "active", "target_date": "2026-05-15" } ``` For portfolio-style initiatives (grouping projects): ```json { "title": "Q2 Platform Rewrite", "description": "Migrate all services to new architecture", "owner_id": "member-uuid", "start_date": "2026-04-01", "target_date": "2026-06-30" } ``` Use `title` for create/update requests; create also accepts legacy `name`. Atoll keeps the legacy `name` field in sync for compatibility. Create accepts `goalId`, `ownerId`, and `targetDate` aliases for `goal_id`, `owner_id`, and `target_date`. Add/remove projects with `{ "project_id": "uuid" }`. ## Automation Rule Fields ```json { "name": "Auto-assign urgent bugs", "trigger_event": "issue.created", "conditions": [{ "field": "priority", "operator": "eq", "value": 0 }], "actions": [{ "type": "set_assignee", "value": "member-uuid" }], "enabled": true, "project_id": "project-uuid" } ``` **Dry-run test**: Send `{ "issue_id": "uuid" }` or `{ "issue": { "status": "todo", "priority": 2 } }`. Returns `{ matched, actions_that_would_run }`. ## Custom View Fields ```json { "name": "My Sprint View", "filters": { "status": ["in_progress", "todo"], "priority": [0, 1] }, "sort": { "field": "priority", "direction": "asc" }, "display_mode": "board", "color": "#6B7280", "icon": "list" } ``` `display_mode`: `board`, `list`. `filters` and `sort` are freeform JSON. ## Webhook Fields ```json { "url": "https://example.com/webhook", "events": ["issue.created", "issue.updated"], "enabled": true } ``` URL must be HTTPS. Response includes `secret` for HMAC signature verification. ## Heartbeat Response ```json { "agent": { "id": "...", "display_name": "Growth Agent" }, "timestamp": "2026-03-29T12:00:00Z", "goals": [{ "goal": { "id", "title", "status", "target_date" }, "days_remaining": 93, "kpis": [{ "kpi": { "name", "current_value", "target_value" }, "pace_needed": 0.71, "pace_actual": 0.42, "trend": "accelerating", "is_stale": false, "is_off_pace": true, "snapshots_recent": [...] }], "initiatives": [{ "initiative": { "title", "status" }, "expected_impacts": [{ "kpi_id", "expected_impact" }], "total_issues": 8, "completed_issues": 3, "stalled_issues": 2, "blocked_issues": 1 }] }], "standalone_kpis": [...], "assigned_issues": [...], "signals": [ { "type": "kpi_off_pace", "severity": "warning", "message": "..." } ] } ``` ## Analytics Response ```json { "statusDistribution": [{ "status": "done", "count": 42 }], "priorityBreakdown": [{ "priority": 1, "count": 15 }], "assigneeWorkload": [{ "assignee_id": "...", "display_name": "...", "count": 8 }], "dailyCounts": [{ "date": "2026-03-01", "created": 5, "completed": 3 }] } ``` --- ## Enums | Domain | Field | Values | |--------|-------|--------| | Task | `status` | `backlog`, `todo`, `in_progress`, `done`, `cancelled` (custom per project via board-columns) | | Task | `priority` | `0` (urgent), `1` (high), `2` (medium), `3` (low) | | Task | `recurrenceType` | `daily`, `weekly`, `monthly`, `yearly` | | Goal | `status` | `active`, `achieved`, `missed`, `paused`, `cancelled` | | KPI | `unit` | `count`, `percentage`, `currency`, `duration`, `ratio`, `custom` | | KPI | `target_direction` | `increase`, `decrease`, `maintain` | | KPI | `source_type` | `manual`, `webhook`, `api_poll`, `formula` | | KPI snapshot | `source` | `manual`, `webhook`, `api_poll`, `formula`, `agent` | | Initiative | `status` | `proposed`, `active`, `completed`, `paused`, `cancelled` | | Status update | `status` | `on_track`, `at_risk`, `off_track` | | Member | `role` | `owner`, `admin`, `member`, `guest` | | Project member | `accessLevel` | `view`, `edit`, `admin` | | Automation | `trigger_event` | `issue.created`, `issue.status_changed`, `issue.assigned`, `issue.priority_changed` | | Heartbeat signal | `type` | `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `webhook_failing` | | Heartbeat signal | `severity` | `info`, `warning`, `critical` | | Custom view | `display_mode` | `board`, `list` | ## Response Format All endpoints return JSON. Successful: `200` or `201`. Errors: `{ "error": "message" }` with `400`, `401`, `402`, `403`, `404`, `409`, or `500`. REST list responses use resource-specific keys by default. Main list endpoints support `?shape=envelope` or `?response_shape=cli` to return `{ resource, items, total, limit, offset, nextOffset, truncated, hint }`. ## Notes - All timestamps are ISO 8601 in UTC - Description and comment fields support Markdown - Board columns (statuses) are customizable per project -- query `/board-columns` for available statuses - Default statuses for new projects: `backlog`, `todo`, `in_progress`, `done` - `cancelled` is always valid but not shown on the board - Agent actions appear in the activity feed with the agent's name - Changes via API appear in real-time on the web board