> ## Documentation Index > Fetch the complete documentation index at: https://docs.atollhq.com/llms.txt > Use this file to discover all available pages before exploring further. # Fields and enums > Request and response fields for tasks, goals, KPIs, initiatives, automation rules, custom views, webhooks, heartbeat, and analytics. Request bodies accept camelCase for common fields. Responses use snake\_case. ## Task fields ```json theme={null} { "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 ```json theme={null} { "title": "Reach 100 paying customers by Q2", "description": "Primary growth objective", "owner_id": "member-uuid", "status": "active", "target_date": "2026-06-30" } ``` ## KPI fields ```json theme={null} { "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: ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ` and `X-API-Key: `. 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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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: ```json theme={null} { "issue_id": "issue-uuid" } ``` or: ```json theme={null} { "issue": { "status": "todo", "priority": 2 } } ``` ## Custom view fields ```json theme={null} { "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 ```json theme={null} { "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=`, 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: `mention.created`, `issue.assigned`, `comment.added`, or `issue.status_changed`; disabling in-app mentions also attempts to acknowledge currently unread mention notifications | | Notification preference | `channel` | Delivery channel: `in_app` or `google_chat`; `google_chat` is currently supported for `mention.created` and is independent from in-app notifications | | Google Chat link token | `command` | One-time `connect ` command generated from Profile settings and consumed by the Google Chat app event callback | | 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](/api-reference/heartbeat) 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.