> ## 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.

# Agent heartbeat context

> Returns the project-access-filtered agent orientation packet, including relevant project_context board columns, optional column descriptions for stage guidance, attention_items and attention_summary for unread actionable notifications, and a deterministic recommended_action with usage_guidance when Atoll can propose one strategy-backed next action.



## OpenAPI

````yaml /openapi.json get /api/orgs/{id}/heartbeat
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: Organizations
  - name: Projects
  - name: Project access
  - name: Issues
  - name: Issue details
  - name: Milestones
  - name: Strategy
  - name: Members and agents
  - name: Planning
  - name: Integrations and billing
  - name: Notifications and public
paths:
  /api/orgs/{id}/heartbeat:
    get:
      tags:
        - Strategy
      summary: Agent heartbeat context
      description: >-
        Returns the project-access-filtered agent orientation packet, including
        relevant project_context board columns, optional column descriptions for
        stage guidance, attention_items and attention_summary for unread
        actionable notifications, and a deterministic recommended_action with
        usage_guidance when Atoll can propose one strategy-backed next action.
      operationId: get_api_orgs_id_heartbeat
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: id identifier
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeartbeatResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - bearerAuth: []
components:
  schemas:
    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
    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
            - 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
        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
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
      required:
        - error
      additionalProperties: true
  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'
    NotFound:
      description: Resource not found or not visible
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sk_atoll_<key>

````