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

# Agents

> Create and manage AI agent accounts

Agent management endpoints are called by humans and org automations (dashboard session auth) — not by agents themselves. Agents interact through the [MCP server](/mcp-tools/overview).

## Create agent

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

Creates an agent with a non-custodial crypto wallet, a spending policy, and (bundled) its first API key.

```json theme={null}
{
  "name": "Ad Spender",
  "teamId": "b2f1c7ce-…",
  "budgetCents": 50000,
  "description": "Manages Google Ads campaigns",
  "autoApprovalThresholdCents": 5000
}
```

| Field                        | Required | Notes                                                                                                |
| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `name`                       | ✓        | 1–100 characters                                                                                     |
| `teamId`                     | ✓        | The team whose budget the agent draws from                                                           |
| `budgetCents`                | ✓        | Total budget, integer cents                                                                          |
| `description`                | —        | Up to 500 characters                                                                                 |
| `autoApprovalThresholdCents` | —        | `0` = every payment needs approval · amount = approve above it · `null` = auto-approve within budget |
| `scopes`                     | —        | Restrict which MCP tools the key may call; omit for the full toolset                                 |

The response includes the agent and its API key — **the key is returned once and never again**.

## List agents

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

Returns the organization's agents. Optional filters: `projectId`, `teamId`.

## Update agent

```bash theme={null}
PATCH /v1/agents/:id                # name, description, appearance
PATCH /v1/agents/:id/budget-policy  # budget + spending ceilings (step-up auth)
```

The budget-policy endpoint updates `budgetCents`, `autoApprovalThresholdCents`, `perTransactionLimitCents`, `dailySpendLimitCents`, and hourly/daily velocity limits. It takes a `version` token from the last read for optimistic concurrency, and requires step-up re-verification.

## Pause and resume

```bash theme={null}
POST /v1/agents/:id/pause
POST /v1/agents/:id/resume
```

Pausing is instant and reversible — every payment is denied while paused, and the API key stays intact. See [Agent Lifecycle](/concepts/agent-lifecycle).

## API keys

```bash theme={null}
POST   /v1/agents/:id/key   # mint a new key (step-up auth)
DELETE /v1/agents/:id/key   # revoke the active key (step-up auth)
```

One active key per agent. Minting for an archived agent returns `409 AGENT_ARCHIVED`.

## Archive agent

```bash theme={null}
DELETE /v1/agents/:id
```

Terminal: revokes the key and detaches the wallet policy. Requires step-up auth. Archived agents cannot be reactivated.

<Tip>
  For an emergency hard stop, pause the agent and revoke its API key. Everything halts immediately,
  and it's fully reversible.
</Tip>