> For clean Markdown of this page, append .md to its URL. For the complete documentation index, see https://www.superagent.sh/llms.txt.


Create persistent Agent assets, configure red teaming, and manage runtime pairing, groups, rules, and alerts through REST.

# Agents

The Agents API exposes persistent Agent assets and the endpoint-monitoring resources available in the **Agents** dashboard. Organization management requests use an API key:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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
**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](https://www.superagent.sh/docs/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:

```json
{
  "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.

## Next steps

- [Configure Runtime Guardrails](https://www.superagent.sh/docs/security-workers/agent-guardrails/runtime)
- [Use Superagent MCP](https://www.superagent.sh/docs/mcp)
- [Subscribe to Agent events with Webhooks](https://www.superagent.sh/docs/webhooks)

---
Source: https://www.superagent.sh/docs/api/agents
Index: https://www.superagent.sh/llms.txt