Fields and enums - Atoll Docs

Request bodies accept camelCase for common fields. Responses use snake_case.

Task fields

{
  "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"]
}

Most fields work on create and update unless a route says otherwise. labelIds is accepted on task create and bulk create. For existing tasks, use the label endpoints or atoll label add/remove. startDate and dueDate are date-only values in YYYY-MM-DD format. Recurring tasks use dueDate to compute the next generated task when the current task moves to done. Task detail responses include enriched member objects for creator, assignee, and assignees; each creator/assignee object includes id, display_name, type, and avatar_url when available.

Goal fields

{
  "title": "Reach 100 paying customers by Q2",
  "description": "Primary growth objective",
  "owner_id": "member-uuid",
  "status": "active",
  "target_date": "2026-06-30"
}

KPI fields

{
  "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
}

Calculated task-completion KPIs use source_type: "formula" and are calculated from linked work instead of snapshots:

{
  "name": "mvp_tasks_done",
  "goal_id": "goal-uuid",
  "source_type": "formula",
  "source_config": {
    "formula": "goal_linked_issue_completion",
    "done_statuses": ["done"]
  }
}

For goal_linked_issue_completion, current_value is the count of non-archived directly linked issues and milestone-linked issues in done status and target_value is the total non-archived directly linked issue and milestone-linked issue count under initiatives for the goal.

KPI snapshot fields

{
  "value": 34,
  "source": "agent",
  "attribution_note": "Checked Stripe dashboard",
  "attributed_to_initiative_id": "initiative-uuid",
  "attributed_to_issue_id": "issue-uuid"
}

Recording a snapshot updates the KPI’s current_value. KPI-to-initiative impact links are separate from snapshot attribution. A link means the initiative is expected to move the KPI; snapshot attribution identifies the initiative and/or issue that produced one measurement. Calculated KPIs do not accept manual snapshots. api_poll snapshots are written by published KPI HTTP Syncs and include first-class provenance: source_sync_id, source_sync_run_id, source_config_hash, source_recorded_for, observed_at, and optional provider_recorded_at.

KPI HTTP sync fields

{
  "name": "PostHog visitors",
  "status": "draft",
  "schedule": "daily",
  "request_config": {
    "method": "GET",
    "url": "https://us.posthog.com/api/projects/123/query/",
    "headers": {
      "Authorization": {
        "secretRef": "posthog_api_key",
        "format": "Bearer {value}"
      }
    }
  },
  "extraction_config": {
    "contentType": "json",
    "pointer": "/results/0/value",
    "numeric": {
      "mode": "number",
      "percentageScale": null
    }
  },
  "freshness_config": {},
  "config_version": 1,
  "config_hash": "sha256:..."
}

KPI HTTP Syncs are constrained generic pollers: GET only, https only, JSON only, exact-host allowlisted, no redirects, no request bodies, no query strings, and no secret values in configs. Draft creation and config validation require the destination host to already be exactly allowlisted. Credential placeholders are limited to Authorization: Bearer <secretRef> and X-API-Key: <secretRef>. Human admins manage exact-host allowlists, secrets, dry-runs, publish, disable, and snapshot-writing run-now actions in Settings > Integrations > KPI syncs. Machine actors can create draft syncs and validate proposed configs only after the host is allowlisted. The org-wide Settings endpoint returns config and secret metadata only to human owners/admins; non-admin members receive redacted status rows, and guests/machine actors are denied.

KPI HTTP sync run fields

{
  "status": "success",
  "recorded_for": "2026-06-03T00:00:00.000Z",
  "observed_at": "2026-06-03T00:01:04.000Z",
  "provider_recorded_at": null,
  "http_status": 200,
  "duration_ms": 348,
  "response_bytes": 2048,
  "extracted_value": 1234,
  "snapshot_id": "snapshot-uuid",
  "error_code": null,
  "redacted_error": null
}

Run history is sanitized. It does not expose request headers, secret values, response bodies, or raw third-party payloads.

Initiative fields

{
  "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",
  "project_id": "project-uuid"
}

Create requests accept either title or legacy name; Atoll stores both fields from the trimmed value. Create requests also accept goalId, ownerId, targetDate, and projectId aliases for goal_id, owner_id, target_date, and project_id. Guest/project-scoped callers must use project_id and have edit/admin access to that project.

Automation rule fields

{
  "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 body:

{
  "issue_id": "issue-uuid"
}

or:

{
  "issue": {
    "status": "todo",
    "priority": 2
  }
}

Custom view fields

{
  "name": "My sprint view",
  "filters": { "status": ["in_progress", "todo"], "priority": [0, 1] },
  "sort": { "field": "priority", "direction": "asc" },
  "display_mode": "board",
  "color": "#6B7280",
  "icon": "list"
}

Webhook fields

{
  "url": "https://example.com/webhook",
  "events": ["issue.created", "issue.updated"],
  "enabled": true
}

The URL must be an HTTPS DNS hostname. IP literals, localhost, and .local hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. The response includes a secret for HMAC verification. Store it immediately; it is shown only once. Delivery requests include X-Atoll-Signature: sha256=<hmac>, where the HMAC-SHA256 key is the SHA-256 hex digest of the webhook secret and the message is the exact raw request body. Delivery requests also include X-Atoll-Delivery-Id for receiver-side deduplication. Delivery history includes retry status and next_retry_at.

Strategy audit fields

GET /api/orgs/{id}/strategy/audit returns findings (sorted critical → warning → info), a summary, and counts_by_type. Each finding:

Field	Type	Description
`type`	string	Finding type (see values below)
`severity`	string	`critical`, `warning`, or `info`
`title`	string	Short human-readable summary
`message`	string	Why it matters
`suggested_fix`	string	Concrete next action (usually the exact API call)
`goal_id` / `kpi_id` / `initiative_id` / `initiative_target_id` / `issue_id` / `milestone_id` / `project_id`	string	Whichever entity ids apply

Finding type values: initiative_orphaned, kpi_orphaned, goal_missing_kpi, goal_missing_initiative, dangling_initiative_project, dangling_initiative_issue, dangling_initiative_milestone (structural); kpi_unrecorded, kpi_missing_target, kpi_stale, kpi_off_pace (KPI health); initiative_missing_impact, initiative_missing_execution, initiative_stalled, initiative_target_missing_execution, initiative_target_overdue, initiative_target_blocked (initiative health); issue_blocked, issue_overdue, milestone_overdue (execution). Strategy audit findings are active-context findings. Paused and cancelled goals are excluded from active goal checks, KPIs attached to inactive goals are skipped for KPI health checks, and paused, completed, or cancelled initiatives are skipped for initiative health checks.

Enums

Domain	Field	Values
Task	`status`	`backlog`, `todo`, `in_progress`, `done`, `cancelled`, or custom board statuses
Board column	`description`	Optional Markdown/plain-text stage criteria or agent guidance; `null` means no guidance
Task	`priority`	`0`, `1`, `2`, `3`
Task update request	`comment_body`	Optional Markdown/plain text or rich-text HTML comment body created with the issue update; stored and returned as sanitized HTML
Task update request	`comment_mentions[].member_id`	Stable Atoll org member ID to mention in the issue update comment created by `comment_body`; not an auth user ID or display name
Comment create request	`mentions[].member_id`	Stable Atoll org member ID to mention in a direct comment API request; recommended for agents and integrations
Comment create response	`mentions.requested`	Count of structured mention targets requested for the created comment
Comment create response	`mentions.created`	Count of mention notifications created or confirmed by the request
Comment create response	`mentions.skipped[]`	Mention targets that did not create notifications; each entry includes `member_id` and `reason`
Comment create response	`mentions.skipped[].reason`	`invalid_member_id`, `not_found`, `self_mention`, `no_project_access`, `guest_unprojected_issue`, `unsupported_member_type`, or `mentions_muted`
Task	`recurrenceType`	`daily`, `weekly`, `biweekly`, `monthly`, `custom`
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`
KPI HTTP sync	`status`	`draft`, `published`, `disabled`
KPI HTTP sync run	`status`	`queued`, `running`, `success`, `error`
Initiative	`status`	`proposed`, `active`, `completed`, `paused`, `cancelled`
Initiative target	`mode`	`progress`, `gate`
Initiative target	`target_direction`	`increase`, `decrease`, `maintain`
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	`severity`	`info`, `warning`, `critical`
Heartbeat attention	`attention_items[]`	Direct current-member notifications such as mentions, assignments, assignee comments, and creator-visible status changes
Heartbeat attention	`attention_items[].ack_endpoint`	Org-scoped endpoint to acknowledge the notification after it is handled
Heartbeat attention	`attention_summary.total_unread`	Count of unread actionable attention items included in the heartbeat
Notification	`event_type`	`mention.created`, `issue.assigned`, `comment.added`, `issue.status_changed`
Notification preference	`event_type`	Notification event type, currently `mention.created` for mention opt-out; disabling in-app mentions also attempts to acknowledge currently unread mention notifications
Notification preference	`channel`	Delivery channel, currently `in_app`
Notification preference	`enabled`	Whether the current member wants this event/channel delivered
Heartbeat project context	`board_columns[].description`	Optional board-column guidance surfaced to agents in `heartbeat --json`
Heartbeat initiative context	`project_ids`	Project IDs connected to an initiative through project, milestone, or issue links
Heartbeat initiative context	`linked_issues`	Accessible issue evidence used for initiative health and recommendations
Heartbeat initiative context	`targets[]`	Initiative target context with linked work, completion, due-soon, overdue, and blocked state
Heartbeat recommendation	`recommended_action.action_type`	`create_work`, `start_work`, `escalate_blocker`, `refresh_metric`; `investigate` and `defer_busywork` are reserved values
Heartbeat recommendation	`suggested_write.operation`	`issue.create`, `issue.update`, `comment.add`, `kpi.snapshot.request`, `none`
Heartbeat recommendation	`quality_checks[].status`	`pass`, `warning`
Heartbeat recommendation	`usage_guidance.preserve_fields[]`	Field names agents should preserve in issue, KPI, status update, or comment writes
Heartbeat recommendation	`usage_guidance.avoid_payload_sources[]`	Context categories agents should avoid copying into write payloads
Custom view	`display_mode`	`board`, `list`

See Heartbeat API for the full recommended_action shape, suggested write fields, and response examples. Initiative targets use fields title, description, mode, unit, unit_label, current_value, target_value, target_direction, target_date, and due_soon_days. Use mode: "progress" for initiative output tracking and mode: "gate" for hard prerequisites. Gate target heartbeat messages use stateful language like 0/5 retailers complete; they do not emit KPI pace.

​Task fields

​Goal fields

​KPI fields

​KPI snapshot fields

​KPI HTTP sync fields

​KPI HTTP sync run fields

​Initiative fields

​Automation rule fields

​Custom view fields

​Webhook fields

​Strategy audit fields

​Enums