Agents API

Agents are the Puck binaries running on your endpoints. The Agents API lets you see which agents are connected, check their heartbeat status, and inspect the runtime configuration the brain has pushed to each one. This is a read-only API — agent configuration is managed through the console’s agent settings page.

All agents endpoints require the agents:read scope.

---

GET /v1/agents

List all agents registered to the account. Results include each agent’s OS profile, last heartbeat timestamp, status, and version. Agents that have not sent a heartbeat in the configured timeout window are listed with status: "disconnected".

Scope required: agents:read

Common query parameters:

Parameter	Description
status	connected, disconnected, or degraded
profile	endpoint-macos, endpoint-linux, or endpoint-windows
tag	Key-value pair, e.g. tag=team:engineering
limit	Page size, 1-1000 (default 100)
cursor	Opaque cursor from a prior response’s next_cursor

curl "https://puck.acme.com/v1/agents?status=connected&profile=endpoint-macos" \
  -H "Authorization: Bearer $PUCK_API_KEY"

const res = await fetch("https://puck.acme.com/v1/agents?status=connected", {
  headers: { Authorization: `Bearer ${process.env.PUCK_API_KEY}` },
});
const { agents, next_cursor } = await res.json();

---

GET /v1/agents/{id}/config

Fetch the runtime configuration currently active on a specific agent — the brain-side view of what the agent should be doing. This includes anomaly weights, active exclusion patterns, poll intervals, and the ID of the last plan distributed to it.

Scope required: agents:read

This is the brain’s record of what was pushed to the agent, not a live read from the endpoint. If an agent is disconnected or mid-reconnect, the config shown here may differ from what is actually running.

curl "https://puck.acme.com/v1/agents/agent_01hx/config" \
  -H "Authorization: Bearer $PUCK_API_KEY"

const res = await fetch(
  `https://puck.acme.com/v1/agents/${agentId}/config`,
  { headers: { Authorization: `Bearer ${process.env.PUCK_API_KEY}` } }
);
const config = await res.json();
console.log("last plan:", config.last_plan_id);