Heartbeat API

Heartbeat is the API endpoint an AI reads to understand what matters and choose its next action. REST, private CLI, and private MCP callers receive compact output by default. Humans who can manage an agent can configure which context sections and generated signals Atoll proactively surfaces. The policy does not change project access. Agents without a saved policy receive the default policy scope and signal behavior. The endpoint is org-scoped, but the response is filtered by the caller’s project access. Owners and admins receive full org context when they request the legacy full view. Members and guests only receive project-bound content for projects they can access. A project-scoped guest receives board context for each explicitly accessible project even before work is assigned or linked into the strategy graph. Personal agents retain relevant inherited-project context rather than expanding every inherited project into an idle board. Non-guest members can also see unprojected org-level strategy. Shared initiatives can appear with issue counts, blocked/stalled health, and signals computed from accessible work only.

GET /api/orgs/{orgId}/heartbeat

Compact response

The default response is a compact envelope. It contains attention_items, attention_summary, grouped actionable signals, a deterministic recommended_action when available, counts, delta, and page. It omits full goals, standalone_kpis, standalone_initiatives, assigned_issues, and project_context collections. The serialized JSON response is bounded to 16,384 UTF-8 bytes and 25 signal groups. The page object reports max_bytes, max_items, returned_count, returned_bytes, has_more, next_cursor, and a terminal ack_cursor. Continue with cursor=<next_cursor> until has_more is false. Only the terminal page includes ack_cursor; after all pages are processed, send it to:

POST /api/orgs/{orgId}/heartbeat/ack
Content-Type: application/json

{"ack_cursor":"<terminal-ack-cursor>"}

Acknowledgement is idempotent. Cursors are opaque, server-issued, and single-use in sequence. Pass the exact next_cursor from the immediately previous page; do not manufacture, skip, or replay a page cursor. Pass an acknowledged terminal cursor as since=<ack-cursor> on a later compact read to receive only new, changed, or escalated groups. Invalid cursors return 400. Stale page cursors and unacknowledged since cursors return 409. If policy, authorization, or the candidate set changes while paging, restart without the cursor after 409 heartbeat_cursor_stale. An expired acknowledged baseline returns a fresh compact response with delta.reset_required: true. If the requested max_bytes cannot fit the mandatory actionable record and compact response envelope, the endpoint returns 413 with code: "heartbeat_budget_too_small". It does not advance a page cursor or terminal receipt. Retry with a larger max_bytes (up to 16,384) or omit the parameter to use the default. Compact attention_items are bounded projections with id, event_type, severity, title, resource_type, and ack_endpoint; resource_id is included when present. Full mode retains the richer attention fields. Compact dependency signals group affected downstream issues under an actionable upstream blocker and release condition. Expected waits are suppressed for an unsatisfied dependency when the readable blocker is before its release column and there is no active stall, threatened or overdue commitment, or explicit deadline, gate, permission, or stale anomaly. An unowned backlog or Todo blocker by itself is an ordinary wait and never alerts. Actionable groups surface active stalls, threatened or overdue commitments, and explicit anomalies; escalation metadata alone does not surface an expected wait. When every dependency fact behind an initiative-target or stalled aggregate is an expected wait, that aggregate is suppressed too. Groups can include a suggested_read with an executable REST path, CLI command, or private MCP tool call. Use ?view=full for the legacy full response. Full requests cannot combine with since or cursor. The public plugin MCP profile keeps the legacy full heartbeat shape and does not expose compact paging or acknowledgement. Private MCP supports compact heartbeat inputs and the atoll_ack_heartbeat tool.

Execution attention

Private REST, CLI, and MCP compact responses also include the separate execution_attention projection:

{
  "execution_attention": {
    "resolved_unread": [],
    "open": []
  },
  "execution_attention_summary": {
    "resolved_unread": 0,
    "open": 0,
    "total": 0
  }
}

Resolved answers appear in resolved_unread until the requesting agent acknowledges the receipt or completes the exact version-fenced waiting -> running transition. Open requests remain in open. The existing 25-item and 16 KiB page limits apply across execution attention, notification attention, and signals; resolved answers are ordered before open requests. Heartbeat page acknowledgement only acknowledges the delivery snapshot and does not consume an execution-attention receipt. An agent acknowledges a resolved answer with:

POST /api/orgs/{orgId}/attention/{attentionId}/ack
Content-Type: application/json

{
  "expected_attention_version": 2,
  "expected_execution_state_version_at_close": 4,
  "idempotency_key": "answer-read-42"
}

The live requesting agent and its current project access are checked at the time of the write. The operation is idempotent for the same key and body, returns 409 for stale versions or key reuse with a different body, and never resumes an execution. Public plugin MCP heartbeat output remains unchanged.

Per-agent policy management

The web app exposes these settings under Heartbeats. The management APIs require an authenticated human who can manage the target agent:

GET /api/orgs/{orgId}/agents/{agentId}/heartbeat-policy
PUT /api/orgs/{orgId}/agents/{agentId}/heartbeat-policy
DELETE /api/orgs/{orgId}/agents/{agentId}/heartbeat-policy
POST /api/orgs/{orgId}/agents/{agentId}/heartbeat-preview

GET returns the saved and effective policy, selectable projects, initiatives, and per-project board columns, plus stale selections. PUT atomically replaces the complete policy. DELETE removes the saved policy and restores default behavior. Preview accepts { "policy": ... } for an unsaved draft or {} for the saved policy and composes the heartbeat as the target agent without persisting changes. When access or entities change, saved_policy retains stale IDs so the real heartbeat and a {} saved preview fail closed instead of treating that dimension as All. effective_policy is the sanitized, editable form and stale_selections identifies what was removed from it. Saving that sanitized form explicitly removes the stale restrictions.

Heartbeat focus narrows proactive signals only. It cannot grant project access, create initiative permissions, or create task-column permissions.

Within projects, initiatives, or columns, selected values use OR semantics. Across configured dimensions, generated signals use AND semantics. Column focus applies only to task signals. Assigned work and direct attention remain visible when their parent sections are enabled. When GitHub workflow verification is enabled for a connection, authorized REST and CLI heartbeat attention can include one verification.completed item for an exact matched repository, pull request, workflow run attempt, and head SHA. Its validated verification object contains only bounded identifiers, the conclusion, a canonical GitHub run URL, and next_action; it never contains raw payloads, secrets, logs, or thread identifiers. The integration is disabled by default and workflow processing remains observe-only unless an owner or admin enables attention mode. The public MCP heartbeat excludes verification.completed. Use the authorized REST endpoint or atoll heartbeat --json for this private integration evidence. An empty project, initiative, or column selection means All. Every signal has one stable category: task, initiative, KPI, or project. Disabled sections retain the response shape with empty collections; disabling attention empties both attention_items and its summary counts. CLI equivalent:

atoll heartbeat --json
atoll heartbeat --explain-kpi paying_customers --json

Legacy full response shape

{
  "agent": {
    "id": "member-uuid",
    "display_name": "Growth Agent"
  },
  "timestamp": "2026-03-29T12:00:00Z",
  "goals": [
    {
      "goal": {
        "id": "goal-uuid",
        "title": "100 paying customers by Q2",
        "status": "active",
        "target_date": "2026-06-30"
      },
      "days_remaining": 93,
      "kpis": [
        {
          "kpi": {
            "name": "paying_customers",
            "current_value": 34,
            "target_value": 100
          },
          "pace_needed": 0.71,
          "pace_actual": 0.42,
          "trend": "accelerating",
          "is_stale": false,
          "is_off_pace": true,
          "snapshots_recent": []
        }
      ],
      "initiatives": [
        {
          "initiative": {
            "title": "Content pipeline",
            "status": "active"
          },
          "expected_impacts": [
            {
              "kpi_id": "kpi-uuid",
              "expected_impact": "+30 signups/mo"
            }
          ],
          "total_issues": 8,
          "completed_issues": 3,
          "stalled_issues": 2,
          "blocked_issues": 1,
          "project_ids": ["project-uuid"],
          "linked_issues": [
            {
              "id": "issue-uuid",
              "title": "Publish comparison page",
              "status": "todo",
              "priority": 1,
              "assignee_id": "member-uuid",
              "project_id": "project-uuid",
              "milestone_id": null,
              "number": 42,
              "blocked": false,
              "updated_at": "2026-03-28T12:00:00Z"
            }
          ]
        }
      ]
    }
  ],
  "standalone_kpis": [],
  "assigned_issues": [],
  "project_context": [
    {
      "project_id": "project-uuid",
      "project_name": "Product",
      "board_columns": [
        {
          "id": "column-uuid",
          "key": "approval_gate",
          "label": "Approval Gate",
          "description": "Use when implementation is complete but needs approval.",
          "position": 4
        }
      ]
    }
  ],
  "signals": [
    {
      "type": "kpi_off_pace",
      "severity": "warning",
      "message": "KPI \"paying_customers\" is off pace: need 0.71/day, actual 0.42/day"
    }
  ],
  "recommended_action": {
    "id": "create_work:kpi-uuid:initiative-uuid",
    "action_type": "create_work",
    "title": "Create Content pipeline work for paying_customers",
    "target_type": "initiative",
    "target_id": "initiative-uuid",
    "goal_id": "goal-uuid",
    "kpi_id": "kpi-uuid",
    "initiative_id": "initiative-uuid",
    "source_signal_ids": ["kpi_off_pace:kpi-uuid"],
    "why_now": "paying_customers is off pace, and Content pipeline has no active linked issue.",
    "expected_impact": "Create the missing execution path for the initiative expected to move paying_customers: +30 signups/mo.",
    "evidence": ["KPI \"paying_customers\" is off pace..."],
    "first_step": "Open Content pipeline and define the smallest task that can move paying_customers.",
    "success_criteria": ["Create or update concrete follow-up actions tied to paying_customers."],
    "suggested_write": {
      "operation": "issue.create",
      "title": "Create Content pipeline work for paying_customers",
      "body": "<h2>Why now</h2>...",
      "status": "todo",
      "priority": 1,
      "project_id": "project-uuid",
      "initiative_id": "initiative-uuid",
      "kpi_id": "kpi-uuid",
      "initiative_target_id": "initiative-target-uuid"
    },
    "confidence": "high",
    "caveats": [],
    "quality_checks": [
      {
        "id": "kpi_link",
        "status": "pass",
        "message": "Recommendation includes a KPI link."
      }
    ],
    "usage_guidance": {
      "instructions": [
        "Prefer suggested_write.operation when it matches the current board state and the recommendation is still current.",
        "Preserve goal, KPI, initiative, initiative target, why-now, expected impact, first step, suggested_write, and success criteria evidence in any issue, status update, KPI refresh, or comment you create.",
        "Do not copy deferred busywork, unrelated tasks, or caveat text into write payloads unless it is directly needed for the recommended action."
      ],
      "preserve_fields": ["goal_id", "kpi_id", "initiative_id", "initiative_target_id", "why_now", "expected_impact", "first_step", "success_criteria", "suggested_write"],
      "avoid_payload_sources": ["deferred_busywork", "unrelated_assigned_issues", "stale_recommendations_after_board_change"]
    }
  }
}

project_context includes ordered board columns for accessible projects relevant to the heartbeat, including optional column descriptions that teams use as stage criteria or agent guidance. attention_items contains direct notifications that require the current member’s attention, including mentions, assignments, assignee comments, direct replies, and creator-visible status changes. Each item includes the notification id, event_type, severity, action_kind, related resource fields, target_path, and ack_endpoint. Comment items can include comment_id; a direct reply can additionally include reply_to_comment_id and the parent agent comment’s validated routing metadata (harness, thread/session ID, and optional host ID). If routing is absent, fetch the new reply through GET /comments/{comment_id} (or list the issue comments) and inspect its shallow reply_to_comment.source_metadata; this remains available when the parent was later soft-deleted. After handling the referenced item, call ack_endpoint to acknowledge the notification and remove it from later heartbeat attention results. attention_summary aggregates unread attention counts by type. Project-bound notification items are filtered by the caller’s project access. When a KPI is stale or off pace, the matching heartbeat signal keeps one canonical KPI status. Its metadata.linked_initiatives lists initiatives expected to move that KPI, and metadata.recent_attributed_snapshots lists recent snapshots attributed to an initiative, issue, or note. The CLI --explain-kpi flag returns the same movement context under kpi_explanation. recommended_action is a deterministic strategy-backed next action built from the heartbeat summary. Action types are create_work, start_work, escalate_blocker, refresh_metric, and investigate. The suggested_write object can prefill a new issue, issue status update, blocker comment, or KPI refresh request; an investigation can use operation: "none" when heartbeat lacks enough detail for a safe write. Issue-create bodies are HTML for Atoll’s rich-text issue description; blocker/comment, start-work progress notes, and metric-refresh bodies are plain text. Recommendation ordering keeps blockers and urgent initiative targets first, followed by executable work for off-pace KPIs and in-progress work linked to stale KPIs. Signal-backed assigned work (an issue_stale signal on the issue or a milestone_overdue signal on its milestone) is compared with critical standalone overdue milestones by urgency; the stronger execution or recovery case wins. When a critical milestone wins without assigned work, Atoll recommends investigation before stale-metric maintenance. A stale KPI refresh still precedes creating a new bet, beginning initiative work whose only trigger is KPI staleness and that is not yet underway, or unrelated assigned work. Agents should follow usage_guidance: prefer suggested_write.operation when it still matches the current board, preserve KPI/initiative/initiative-target/why-now/expected-impact/first-step/success-criteria evidence in any write, and avoid copying deferred busywork or unrelated assigned tasks into issue or comment payloads. When a start_work action uses suggested_write.operation: "issue.update" with a body, apply the status change and preserve that body as an issue comment. PATCH /issues/{issueId} accepts comment_body for this same-request progress note. Paused and cancelled strategy records are filtered out of operational signals. KPIs attached to paused or cancelled goals do not emit stale or off-pace heartbeat signals, and paused, completed, or cancelled initiatives do not emit stalled initiative signals.

Signals

Type	Meaning
`kpi_off_pace`	A KPI is behind required pace
`kpi_stale`	A KPI has not been updated recently enough
`issue_stale`	Assigned issue has had no recent update
`issue_blocked`	Issue is blocked by another issue
`milestone_overdue`	Milestone is overdue
`initiative_stalled`	Initiative has stalled or blocked execution
`initiative_target_due_soon`	Incomplete gate target is inside its due-soon window
`initiative_target_overdue`	Incomplete target is past its target date
`initiative_target_blocked`	Linked target work is blocked
`webhook_failing`	Webhook deliveries are failing

Severity values are critical, warning, and info. Gate target signals are stateful and do not use KPI pace language. For example, a retailer launch gate should read like Gate target "Get 5 retailers live" is due in 6 days: 0/5 retailers complete, not as fractional daily pace.

Agent guidance

Agents should:

Call heartbeat at the start of a run.
Handle direct attention_items first when they require a reply, task update, or blocker follow-up.
Call each handled item’s ack_endpoint.
Sort remaining signals by severity and business leverage.
Inspect the relevant issues, KPI, initiative, or milestone.
Act through CLI or API.
Comment and update records.
Stop when the current unit is complete.

Start here

User guide

Agent guide

CLI

API reference

Integrations

Admin

Changelog

Troubleshooting

Compact response

Execution attention

Per-agent policy management

Legacy full response shape

Signals

Agent guidance

​Compact response

​Execution attention

​Per-agent policy management

​Legacy full response shape

​Signals

​Agent guidance

Compact response

Execution attention

Per-agent policy management

Legacy full response shape

Signals

Agent guidance