The Agents API exposes the same endpoint-monitoring resources available in the Agents dashboard. Organization management requests use an API key:

export SUPERAGENT_API_KEY="sk_live_..."
export SUPERAGENT_API_URL="https://superagent.sh/api/v1"

Clients

Method	Endpoint	Description
GET	/agents/clients	List registered clients
POST	/agents/clients	Register a client and receive a pairing token
GET	/agents/clients/{client_id}	Retrieve a client
PATCH	/agents/clients/{client_id}	Rename a client
DELETE	/agents/clients/{client_id}	Revoke a client and its credentials
POST	/agents/clients/{client_id}/pairing-token	Generate a new pairing token
PUT	/agents/clients/{client_id}/groups	Replace group memberships

Register a client:

curl -X POST "$SUPERAGENT_API_URL/agents/clients" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production runner"}'

The response includes pairing_token and pairing_token_expires_at. The token is shown once, expires after 15 minutes, and is consumed by the first successful pairing.

Assign groups:

curl -X PUT "$SUPERAGENT_API_URL/agents/clients/CLIENT_ID/groups" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_ids":["GROUP_ID"]}'

Groups

Method	Endpoint	Description
GET	/agents/groups	List groups and assignments
POST	/agents/groups	Create a group
GET	/agents/groups/{group_id}	Retrieve a group
PATCH	/agents/groups/{group_id}	Update its name or description
DELETE	/agents/groups/{group_id}	Delete the group
PUT	/agents/groups/{group_id}/rules	Replace rule assignments
PUT	/agents/groups/{group_id}/builtin-rules	Replace built-in rule exclusions

Create a group with initial clients:

curl -X POST "$SUPERAGENT_API_URL/agents/groups" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Production",
    "description":"Production coding agents",
    "client_ids":["CLIENT_ID"]
  }'

Group responses include excluded_builtin_rule_ids, an additive list of
default Numbat rule identifiers that are detached from that group. Custom rule
assignments remain in rule_ids.

Rules

Method	Endpoint	Description
GET	/agents/rules	List security rules
POST	/agents/rules	Create a YAML rule
GET	/agents/rules/{rule_id}	Retrieve a rule
PATCH	/agents/rules/{rule_id}	Replace YAML and group assignments
DELETE	/agents/rules/{rule_id}	Delete the rule
GET	/agents/rules/builtin	List the pinned built-in catalog and effective modes
GET	/agents/rules/builtin/{rule_id}	Retrieve a built-in rule
PATCH	/agents/rules/builtin/{rule_id}	Set monitor, enforce, or disabled mode
DELETE	/agents/rules/builtin/{rule_id}	Restore the shipped default
POST	/agents/rules/validate	Validate YAML without saving
POST	/agents/rules/generate	Generate validated YAML with Kimi K3

Create and assign a rule:

curl -X POST "$SUPERAGENT_API_URL/agents/rules" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "yaml_text":"id: acme.secrets.env_read\nversion: \"1.0\"\ntitle: Environment file read\nseverity: high\nexpr: event.event_type == \"file.read\"\n",
    "group_ids":["GROUP_ID"]
  }'

The API validates the YAML structure before saving. Endpoints perform authoritative rule validation before activating an updated catalog.

Built-in responses distinguish the pinned yaml_text from
effective_yaml_text, and include default_mode, effective_mode, and
override_state. Restoring a built-in rule deletes only the organization's
override; the stable built-in rule identifier remains unchanged. The built-in
catalog supports the standard limit and offset parameters plus exact
category and severity filters.

Alerts

List uploaded findings and enforcement decisions:

curl "$SUPERAGENT_API_URL/agents/records?record_type=finding&client_id=CLIENT_ID" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY"

GET /agents/records supports:

• limit — 1–100, default 25
• offset — number of matching records to skip
• client_id — restrict results to one client
• record_type — finding or enforcement

Use GET /agents/records/{record_id} for unified finding/enforcement detail.
The response is explicitly whitelisted to client, groups, rule, outcome,
evidence, and timeline identifiers. It does not return the arbitrary normalized
event payload.

For live monitoring, connect to GET /agents/logs/stream with
Accept: text/event-stream. The stream uses the same privacy-safe event mapper
as the dashboard and supports Last-Event-ID reconnects. It never includes raw
commands, paths, or tool payloads beyond the existing whitelisted monitor event
fields.

Notifications and webhooks

Generic Notifications and per-user notification preferences are intentionally
not available through organization API keys or MCP. They belong to individual
recipient users, not the organization-scoped Agents management surface.

Organization webhooks provide a durable push integration for Agent alerts.
Subscribe to agent.finding_created and agent.action_blocked from
Settings → Webhooks. Payloads contain privacy-safe client and rule metadata,
plus the durable alert ID and dashboard URL. See Webhooks.

Programmatic integrations can also pull durable Agent alerts through
GET /agents/records, GET /agents/records/{record_id}, or consume the live
REST SSE stream.

Pagination

Client, group, rule, and alert lists use the standard API pagination envelope:

{
  "data": [],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 0,
    "has_more": false
  }
}

Endpoint runtime authentication

The management endpoints above use organization API keys. Paired endpoint clients use their separate revocable client credential for configuration sync, heartbeats, and alert delivery. Do not place an organization API key on a monitored endpoint.

MCP

Agent management operations are also available through the Superagent MCP
server, including built-in catalog and mode management, group exclusions,
validation, generation, and alert detail. MCP does not model the long-lived SSE
transport; use list_agent_alerts and get_agent_alert for snapshots, or the
REST stream for live logs.