Heartbeat — Multica

Agent Presence

Loading dashboard...

💓

No heartbeat data yet

Agents will appear here when they start reporting

Loading agents...

Agent Name	Status	Last Run	Runs (24h)	Actions

No agents found

Loading runs...

ID	Agent	Status	Source	Started	Duration	Error

No runs yet

Trigger Wake

Agent

Source

Reason

Queued Wakeups

Loading wakeups...

ID	Agent	Source	Reason	Status	Requested At	Actions

No wakeup requests

Agent API

REST + MCP endpoints for programmatic heartbeat and wakeup management.

Base URL

https://ss-heartbeat.ocuss.app

Authentication

None required. workspace parameter is mandatory.

GET /api/heartbeat/runs

List heartbeat runs in a workspace, newest first. Optionally filter by agent, status, limit, offset.

Parameters:

workspace (required) Slug or UUID

agent_id (optional) Filter by agent

status (optional) queued|running|completed|failed|cancelled

limit (optional) Max results (default 50, max 200)

offset (optional) Pagination offset

GET /api/heartbeat/runs/{run_id}

Get a single heartbeat run by ID.

Parameters:

workspace (required) Slug or UUID

POST /api/heartbeat/runs

Create a new heartbeat run. Also updates agent_presence.

Body (JSON):

agent_id * Agent UUID

trigger_detail (optional) Free text

PATCH /api/heartbeat/runs/{run_id}

Update a heartbeat run's status, error, or next_action. Also updates agent_presence on status change.

Body (JSON — any subset):

status, error, next_action, finished_at, started_at

Example:

curl -X PATCH "https://ss-heartbeat.ocuss.app/api/heartbeat/runs/$RUN_ID?workspace=$MULTICA_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"status":"running"}'

GET /api/heartbeat/events

List events for a heartbeat run, ordered by sequence.

Parameters:

workspace (required) Slug or UUID

run_id * Run UUID

POST /api/heartbeat/events

Append an event to a run. Auto-increments seq.

Body (JSON):

run_id * Run UUID

message * Event message text

level (optional) info|warn|error|debug

stream (optional) stdout|stderr|tool|state

payload (optional) JSON object

GET /api/heartbeat/wakeups

List wakeup requests in a workspace.

Parameters:

workspace (required) Slug or UUID

agent_id (optional) Filter by agent

status (optional) queued|claimed|completed|cancelled|expired

POST /api/heartbeat/wakeups

Create a wakeup request. Returns 409 Conflict if a duplicate queued wakeup exists within 30 seconds.

Body (JSON):

agent_id * Agent UUID

reason * Wakeup reason text

requested_by_type (optional) member|agent|system

requested_by_id (optional) Requester UUID

payload (optional) JSON object

Example:

curl -X POST "https://ss-heartbeat.ocuss.app/api/heartbeat/wakeups?workspace=$MULTICA_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"AGENT_UUID","source":"user","reason":"Manual wakeup"}'

DELETE /api/heartbeat/wakeups/{wakeup_id}

Cancel a queued wakeup request.

Parameters:

workspace (required) Slug or UUID

GET /api/heartbeat/presence

List all agents with computed current_status (active/stale/offline) and staleness_seconds.

Parameters:

workspace (required) Slug or UUID

Example:

curl "https://ss-heartbeat.ocuss.app/api/heartbeat/presence?workspace=$MULTICA_WORKSPACE_ID"

MCP Tools

MCP heartbeat_request_wakeup(workspace_id, agent_id, source, reason, payload?)

MCP heartbeat_list_runs(workspace_id, agent_id?, status?, limit?)

MCP heartbeat_get_run(workspace_id, run_id)

MCP heartbeat_record_event(workspace_id, run_id, event_type, message, level?, payload?)

MCP heartbeat_get_presence(workspace_id)

MCP heartbeat_complete_run(workspace_id, run_id, status, error?)

Quick Reference

# Get agent presence

curl "https://ss-heartbeat.ocuss.app/api/heartbeat/presence?workspace=$MULTICA_WORKSPACE_ID"

# Create a wakeup request

curl -X POST "https://ss-heartbeat.ocuss.app/api/heartbeat/wakeups?workspace=$MULTICA_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"AGENT_UUID","source":"user","reason":"Please investigate"}'

# List heartbeat runs

curl "https://ss-heartbeat.ocuss.app/api/heartbeat/runs?workspace=$MULTICA_WORKSPACE_ID&status=running"

# Complete a run

curl -X PATCH "https://ss-heartbeat.ocuss.app/api/heartbeat/runs/$RUN_ID?workspace=$MULTICA_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"status":"completed"}'

# Cancel a queued wakeup

curl -X DELETE "https://ss-heartbeat.ocuss.app/api/heartbeat/wakeups/$WAKEUP_ID?workspace=$MULTICA_WORKSPACE_ID"