> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmuster.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Manage your AI agent registry via the REST API.

## List agents

```bash theme={null}
GET /api/v1/agents
```

**Query parameters:**

| Parameter    | Type   | Description                                                  |
| ------------ | ------ | ------------------------------------------------------------ |
| `status`     | string | Filter by status: `APPROVED`, `DISCOVERED`, `PENDING_REVIEW` |
| `risk_level` | string | Filter by risk: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`          |
| `framework`  | string | Filter by framework: `LANGGRAPH`, `N8N`, etc.                |
| `department` | string | Filter by department name                                    |
| `no_owner`   | bool   | Show only agents with no owner                               |
| `search`     | string | Search by name                                               |
| `sort_by`    | string | `risk_score` (default), `name`, `created_at`                 |
| `sort_dir`   | string | `desc` (default), `asc`                                      |
| `limit`      | int    | Max results, default 100, max 500                            |

**Example:**

```bash theme={null}
curl https://app.getmuster.io/api/v1/agents?risk_level=CRITICAL \
  -H "Authorization: Bearer {token}"
```

**Response:**

```json theme={null}
[
  {
    "agent_id": "uuid",
    "name": "invoice-processor-v2",
    "framework": "LANGGRAPH",
    "risk_level": "HIGH",
    "risk_score": 55,
    "status": "APPROVED",
    "owner_email": "finance@acme.com",
    "department": "Finance",
    "contains_pii": true,
    "external_llm_calls": true,
    "writes_to_systems": true,
    "hitl_required": true,
    "primary_model": "gpt-4o",
    "probe_reachable": true,
    "probe_tls_valid": true,
    "created_at": "2026-02-07T06:00:00Z",
    "updated_at": "2026-03-24T06:00:00Z"
  }
]
```

## Get agent

```bash theme={null}
GET /api/v1/agents/{agent_id}
```

## Create agent

```bash theme={null}
POST /api/v1/agents
```

**Body:**

```json theme={null}
{
  "name": "fraud-detector-v3",
  "framework": "AUTOGEN",
  "owner_email": "risk@acme.com",
  "department": "Risk",
  "contains_pii": true,
  "writes_to_systems": true,
  "hitl_required": false,
  "primary_model": "gpt-4o",
  "model_provider": "openai"
}
```

## Update agent

```bash theme={null}
PATCH /api/v1/agents/{agent_id}
```

## Registry stats

```bash theme={null}
GET /api/v1/registry/stats
```

Returns counts by status, risk level, and flags:

```json theme={null}
{
  "total": 23,
  "approved": 23,
  "critical": 1,
  "high": 8,
  "medium": 9,
  "low": 5,
  "no_owner": 5,
  "has_discrepancies": 2
}
```

## Beacon auto-registration

```bash theme={null}
POST /api/v1/agents/beacon
```

Called automatically by `beacon.register()`. No auth required.

```json theme={null}
{
  "agent_id": "invoice-processor-v2",
  "version": "2.1.0",
  "framework": "LANGGRAPH",
  "endpoint_url": "https://agent.internal.acme.com"
}
```