> ## 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. # Preview an agent heartbeat > Composes the heartbeat as the target agent using its project authorization and either the saved policy or a validated unsaved draft. Drafts are not persisted. ## OpenAPI ````yaml /openapi.json post /api/orgs/{id}/agents/{agentId}/heartbeat-preview openapi: 3.1.0 info: title: Atoll API version: 1.0.0 description: >- REST API for Atoll project management, agent collaboration, strategy tracking, and integrations. servers: - url: https://atollhq.com description: Production security: - bearerAuth: [] tags: - name: Authentication - name: Organizations - name: Projects - name: Project access - name: Issues - name: Issue details - name: Milestones - name: Strategy - name: Members and agents - name: Planning - name: Setup - name: Integrations and billing - name: Notifications and public - name: Private inbox paths: /api/orgs/{id}/agents/{agentId}/heartbeat-preview: post: tags: - Agents summary: Preview an agent heartbeat description: >- Composes the heartbeat as the target agent using its project authorization and either the saved policy or a validated unsaved draft. Drafts are not persisted. operationId: preview_agent_heartbeat parameters: - name: id in: path required: true schema: type: string - name: agentId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HeartbeatPreviewRequest' examples: saved: summary: Preview saved effective policy value: {} draft: summary: Preview an unsaved draft value: policy: sections: goals: true standalone_kpis: true standalone_initiatives: true assigned_issues: true project_context: true signals: true attention: true signal_categories: task: true initiative: true kpi: false project: true project_ids: [] initiative_ids: [] columns: [] responses: '200': description: Target-agent heartbeat and preview state content: application/json: schema: $ref: '#/components/schemas/HeartbeatPreviewResponse' example: heartbeat: agent: id: agent-uuid display_name: Planner timestamp: '2026-08-11T00:00:00Z' goals: [] standalone_kpis: [] standalone_initiatives: [] assigned_issues: [] project_context: [] signals: [] attention_items: [] attention_summary: mentions: 0 assignments: 0 blockers: 0 total_unread: 0 recommended_action: null preview: draft '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: schemas: HeartbeatPreviewRequest: type: object additionalProperties: false properties: policy: $ref: '#/components/schemas/HeartbeatPolicyInput' HeartbeatPreviewResponse: type: object additionalProperties: false required: - heartbeat - preview properties: heartbeat: $ref: '#/components/schemas/HeartbeatResponse' preview: type: string enum: - default - customized - draft HeartbeatPolicyInput: type: object additionalProperties: false required: - sections - signal_categories - project_ids - initiative_ids - columns properties: sections: type: object additionalProperties: false required: - goals - standalone_kpis - standalone_initiatives - assigned_issues - project_context - signals - attention properties: goals: type: boolean standalone_kpis: type: boolean standalone_initiatives: type: boolean assigned_issues: type: boolean project_context: type: boolean signals: type: boolean attention: type: boolean signal_categories: type: object additionalProperties: false required: - task - initiative - kpi - project properties: task: type: boolean initiative: type: boolean kpi: type: boolean project: type: boolean project_ids: type: array items: type: string format: uuid initiative_ids: type: array items: type: string format: uuid columns: type: array items: type: object additionalProperties: false required: - project_id - column_id properties: project_id: type: string format: uuid column_id: type: string format: uuid HeartbeatResponse: type: object additionalProperties: true required: - agent - timestamp - goals - standalone_kpis - assigned_issues - project_context - signals - attention_items - attention_summary properties: agent: type: object additionalProperties: true required: - id properties: id: type: string display_name: type: string nullable: true timestamp: type: string format: date-time goals: type: array items: type: object additionalProperties: true standalone_kpis: type: array items: type: object additionalProperties: true assigned_issues: type: array items: type: object additionalProperties: true project_context: type: array items: type: object additionalProperties: true signals: type: array items: type: object additionalProperties: true attention_items: type: array items: $ref: '#/components/schemas/AttentionItem' attention_summary: $ref: '#/components/schemas/AttentionSummary' recommended_action: type: object nullable: true additionalProperties: true Error: type: object description: >- Common error responses contain error. Shared missing-auth and unknown-API responses also contain a stable code. properties: error: type: string code: type: string required: - error examples: - error: Unauthorized code: unauthorized - error: Not found code: not_found additionalProperties: true AttentionItem: type: object additionalProperties: false required: - id - source - event_type - severity - action_kind - resource_type - resource_id - issue_id - project_id - title - target_path - ack_endpoint - created_at properties: id: type: string source: type: string enum: - notification event_type: type: string examples: - mention.created - issue.assigned - comment.added - issue.status_changed severity: type: string enum: - info - warning - critical - action_required action_kind: type: string examples: - reply_to_comment - resume_agent_thread - start_work - review resource_type: type: string resource_id: type: string nullable: true issue_id: type: string nullable: true project_id: type: string nullable: true comment_id: type: string nullable: true reply_to_comment_id: type: string nullable: true routing: allOf: - $ref: '#/components/schemas/CommentSourceMetadata' nullable: true title: type: string target_path: type: string nullable: true ack_endpoint: type: string created_at: type: string format: date-time description: >- Direct current-member notification surfaced in heartbeat for agent attention workflows. AttentionSummary: type: object additionalProperties: false required: - mentions - assignments - blockers - total_unread properties: mentions: type: integer minimum: 0 assignments: type: integer minimum: 0 blockers: type: integer minimum: 0 total_unread: type: integer minimum: 0 CommentSourceMetadata: type: object additionalProperties: false required: - harness anyOf: - required: - thread_id - required: - session_id properties: harness: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$ examples: - codex - claude-code thread_id: type: string minLength: 1 maxLength: 255 session_id: type: string minLength: 1 maxLength: 255 host_id: type: string minLength: 1 maxLength: 255 description: >- Hidden routing provenance for agent-authored comments. Omit this object unless the host exposes a real thread or session ID, and never invent one. Contains harness identifiers only; never include credentials, prompts, or arbitrary runtime state. responses: BadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Authenticated but not allowed content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: sk_atoll_ ````