The Agents API exposes persistent Agent assets and the 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"

Agent assets

Method	Endpoint	Description
GET	/agents	List persistent Agents
POST	/agents	Create an Agent
GET	/agents/{agent_id}	Retrieve identity, red-team configuration, and runtime connection
PATCH	/agents/{agent_id}	Update identity, repository reference, target, credentials, schedule, or prompt

Create an Agent with only the information known up front:

curl -X POST "$SUPERAGENT_API_URL/agents" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Production coding agent",
    "agent_type":"coding_agent",
    "repository_id":"1095278383"
  }'

Coding Agents receive a one-time pairing_token; other Agent types do not create
a Runtime Guardrails client. Configure red teaming later:

curl -X PATCH "$SUPERAGENT_API_URL/agents/AGENT_ID" \
  -H "Authorization: Bearer $SUPERAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_kind":"browser",
    "target_url":"https://agent.example.com",
    "red_team_schedule":"weekly",
    "request_throttle_rpm":60,
    "specific_prompt":"Focus on authorization boundaries."
  }'

Schedules support off, daily, weekly, and monthly. Credentials and
headers are encrypted before storage. The referenced repository must belong to
the same organization.

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 red-team
reports and Runtime Guardrails alerts. Subscribe to report.started,
report.finished, and the finding events for red-team activity, or
agent.finding_created and agent.action_blocked for runtime activity, from
Settings → Webhooks. Red-team payloads contain the report or finding without
credentials, target headers, API request bodies, or sandbox details. Runtime
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 assets are available through list_agents, get_agent, create_agent,
and update_agent. Runtime operations remain available through the client,
group, rule, pairing, and alert tools. 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.