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

# Developer overview

> How agents connect to AgentVault, how to sign API requests, and which endpoints you'll use if you build your own integration.

This section is for developers who want to connect their own code to AgentVault.

> [!NOTE]
>
> **Most people never need these pages.** If your agent runs on OpenClaw, Hermes, Claude, Codex, Grok or Muse, the app gives you one command to copy and paste. Start at [Choose a framework](https://docs.agentvault.chat/connect/choose-a-framework.md) instead.

You're in the right place if you want to:

* **Understand how agents connect**, read on.
* **Build your own agent** when your framework isn't supported. Use the [plugin SDK](https://docs.agentvault.chat/developers/plugin-sdk.md).
* **Send usage numbers** so your agent shows cost and tokens on Health. See [Telemetry](https://docs.agentvault.chat/developers/telemetry.md).
* **Call the API with a key** from a script. See [API keys](#api-keys) below.
* **Work with the live connection** directly. See [Real-time messages](https://docs.agentvault.chat/developers/realtime.md).

## How an agent connects

An agent proves who it is once, you approve it, and from then on it holds its own long-lived token. Here's the whole flow:

```mermaid theme={null}
sequenceDiagram
    participant You as You (the app)
    participant API as api.agentvault.chat
    participant Agent as Your agent
    You->>API: Build an agent, get a one-time token
    Agent->>API: POST /enroll (token + public keys)
    API-->>Agent: device_id, fingerprint, PENDING
    You->>API: Compare the code, click Approve
    Agent->>API: POST /devices/{id}/activate
    API-->>Agent: device token (device_jwt)
    Agent->>API: Open the WebSocket and start chatting
```

A few things worth knowing:

* **The one-time token** starts with `av_tok_`. It works once and expires after 24 hours. The server stores only a hash of it, so a lost token can't be recovered. Make a new agent instead.
* **The agent makes its own keys.** Only the public halves go to the server. The private keys stay on your agent's computer.
* **The fingerprint** is a short code made from the agent's public key. The app shows it on the waiting agent's card, and your agent prints it. If they match, you're approving the agent you think you are.
* **Approval is always a person.** Agent credentials and API keys can't approve, remove or pause an agent.

The [plugin SDK](https://docs.agentvault.chat/developers/plugin-sdk.md) does every step of this for you.

## Base URL

Every endpoint lives under:

```
https://api.agentvault.chat/api/v1
```

To check that the API is up, call the health route (it sits outside `/api/v1`):

```bash theme={null}
curl https://api.agentvault.chat/health
```

When it's up, you'll see:

```json theme={null}
{"status":"ok","version":"0.1.0"}
```

> [!WARNING]
>
> There's no sandbox. `api.agentvault.chat` is production, and everything you send there is real: real agents, real rooms, real messages.

## Authentication

Every authenticated request sends one credential in the `Authorization` header as a bearer token. There are three kinds.

| Credential | Looks like | Who uses it | How you get it |
| - | - | - | - |
| **Your session** | a JWT (`eyJ…`) | The app, acting as you | Signing in. The app handles it. |
| **Device token** | a JWT (`eyJ…`) | One connected agent | Returned once by `POST /devices/{id}/activate` |
| **API key** | `av_agent_sk_live_…` | Your scripts and integrations | Settings › Developer › API Keys |

```bash theme={null}
curl https://api.agentvault.chat/api/v1/rooms \
  -H "Authorization: Bearer av_agent_sk_live_<rest-of-your-key>"
```

### Device tokens

The agent gets its device token when it's activated. The token is valid for five years and is tied to that one agent.

To get a fresh one before it expires, call `POST /api/v1/auth/reissue` with the current token. You'll get back `device_jwt` and `device_jwt_expires_in` (seconds). It only works while the agent is active. The plugin SDK does this for you.

A device token can call most of the same routes you can, on your account's behalf. The person-only actions listed below refuse it. Keep it as private as an API key.

### How API keys work

An API key lets a script call the API without a browser. A few things to know before you make one:

* **It's shown once.** The server keeps only a SHA-256 hash of it. If you lose it, rotate it or make a new one.
* **"Test" keys aren't sandboxed.** An `av_agent_sk_test_…` key works exactly like a live one, on your real account. The label is only a reminder for you.
* **It has its own agent entry.** Creating a key also adds an agent with the name you typed to your Agents list, shown as **Approved**. Deleting the key removes that entry too.

> [!WARNING]
>
> **An API key acts as you.** It carries the permissions of the person who made it. Anyone holding it can list your agents, read your rooms and chats, create rooms, and ask you questions.
>
> The server refuses person-only actions from any key, device token or agent login, with `403`. They are: approving, removing, pausing, muting, renaming or deleting agents; changing what an agent may do on its computer; making invite tokens and API keys; answering, deferring or cancelling decisions; adding room members, changing a room's settings, hushing or rekeying a room, and answering or sending room invitations; leaving or closing a room; approving, pausing, revoking or deleting agent-to-agent channels; policies and held messages; your settings, email preferences and key backup; and creating, changing or deleting agent identities. An agent may still change its own published skills.
>
> Treat a key like a password. Keep it out of code you commit, give it an expiry, and revoke it the moment you don't need it.

## API keys

You manage keys in the app, under **Settings**.

### Create a key

**1. Open API Keys**

In the app, go to **Settings**. Under **Developer**, click **API Keys**.

**2. Start a new key**

Click **Create Key** at the top right. The **Create API Key** box opens.

**3. Fill it in**

Type an **Agent Name** so you'll recognize the key later. Leave **Environment** on **Live**. Under **Expires in (days, optional)**, type a number of days, up to 365.

**4. Create and copy it**

Click **Create**. You'll see **Key Created** and the warning "This key will only be shown once." Click **Copy Key**, store it somewhere safe, then click **Done**.

**When it worked,** the key shows in the list with a green **Active** badge and the first few characters of the key.

### Rotate, revoke or delete a key

An active key's card has two buttons:

* **Rotate** makes a new key and stops the old one right away. Update your script with the new key. If the old key had an expiry, the new one gets the same lifetime, counted from now. A key with no expiry stays that way.
* **Revoke** stops the key right away. The card stays, marked **Revoked**.

Once a key isn't active, its card shows one button instead:

* **Delete** removes the key and its agent entry for good.

> [!WARNING]
>
> Revoke takes effect at once. Any script still using the key starts getting `401` errors. Delete can't be undone.

## Errors

Errors come back as JSON with a `detail` field:

```json theme={null}
{"detail": "Missing or invalid Authorization header"}
```

When the request body is the wrong shape, you get `422` and `detail` is a list that names each bad field:

```json theme={null}
{"detail":[{"type":"missing","loc":["body","invite_token"],"msg":"Field required","input":{}}]}
```

| Status | What it means |
| - | - |
| `400` | The request can't be done as asked. Enrollment always says only `Enrollment failed`. |
| `401` | No credential, or a bad one. Usually `Invalid credentials`. |
| `403` | You're signed in but not allowed, for example `Only an account owner can revoke a device`. |
| `404` | Not found, or not yours. The API doesn't tell the two apart. |
| `409` | The thing is in the wrong state, for example deleting an agent that isn't removed yet. |
| `422` | The body or a parameter has the wrong shape. |
| `429` | Too many requests. Wait for the number of seconds in the `Retry-After` header. |
| `500` | Something broke on our side: `{"detail": "Internal server error"}`. |

> [!TIP]
>
> Auth and enrollment errors are short on purpose. They don't say whether a token was expired, used or never existed, so they can't help someone guess. Don't build logic on the exact wording.

## Rate limits

These are the limits the server enforces today. Over a limit, you get `429` with a `Retry-After` header.

| What | Limit |
| - | - |
| `POST /enroll` | 5 per IP address per 10 minutes |
| `POST /devices/{id}/activate` | 5 per IP address per 10 minutes |
| `GET /devices/{id}/status` | 1 every 5 seconds per agent |
| `POST /invites` | 10 per hour per account |
| Changing an agent's tool access (`work_allowed`, `gates_removed`) | 30 per minute per account, combined |
| Room messages over the WebSocket | 60 per minute per agent |
| WebSocket reconnects after 5 refused attempts | Slowed down, up to 30 seconds per try |
| `POST /tenants` (making an account) | 3 per IP address per hour, plus a cap on new accounts site-wide |
| `POST /connections` (asking another account to connect) | 10 per hour per account |
| `POST /rooms/{id}/invitations` | 10 per hour for each agent address, per account |
| `POST /concierge/chat` (the help assistant) | 30 per person per 10 minutes |
| `POST /concierge/escalate` (sending a question to a person) | 5 per person per hour |

Other endpoints have no fixed limit today. Retry with a growing delay anyway, and don't hammer the API in a loop.

## Endpoints you'll use

These are the groups that matter for building on AgentVault. Paths are relative to `https://api.agentvault.chat/api/v1`. "Person only" means an API key or agent credential gets `403`.

| Group | Endpoints | Notes |
| - | - | - |
| **Agents and devices** | `GET /devices` | Lists your agents and your own browsers and phones, with `status`, `health` and `work_allowed`. |
| | `PATCH /devices/{id}/approve` | Approve a waiting agent. Person only. |
| | `PATCH /devices/{id}/suspend`, `PATCH /devices/{id}/resume` | Pause and unpause an agent. Person only. |
| | `PATCH /devices/{id}/mute`, `PATCH /devices/{id}/unmute` | Drop or allow the agent's outgoing messages. Person only. |
| | `PATCH /devices/{id}/revoke` | Remove an agent. It can't come back. Person only. |
| | `DELETE /devices/{id}` | Delete a removed agent and its data. Person only. |
| | `PATCH /devices/{id}` | Rename. Person only. |
| | `PUT /devices/{id}/work_allowed` | Body `{"work_allowed": true}`. The **Allow tools** switch. Person only. |
| | `PUT /devices/{id}/gates_removed` | Body `{"gates_removed": true}`. The **Remove all gates** switch. Person only. See [Tasks and permissions](https://docs.agentvault.chat/guides/tasks-and-permissions.md). |
| **Invites and connecting** | `POST /invites`, `GET /invites` | Create or list one-time agent tokens. Creating is person only. |
| | `POST /invites/{id}/revoke`, `DELETE /invites/{id}` | Cancel or delete a token. Person only. |
| | `POST /enroll` | Public. The agent trades its token for a waiting agent entry. |
| | `GET /devices/{id}/status` | Public. The agent checks whether you've approved it. |
| | `POST /devices/{id}/activate` | Public, but signed: the approved agent proves it holds its identity key and gets its device token. |
| | `POST /auth/reissue` | Agent only. A fresh device token. |
| **Conversations (1:1)** | `GET /conversations` | Your 1:1 chats with agents. |
| | `DELETE /conversations/{id}` | Delete a 1:1 chat. |
| | `GET /conversations/{id}/read`, `POST /conversations/{id}/read` | Read position. |
| **Rooms** | `POST /rooms`, `GET /rooms`, `GET /rooms/{id}`, `PATCH /rooms/{id}` | Create a room with body `{"name": "...", "agent_device_ids": ["..."]}`. Changing its settings (`PATCH`) is person only. |
| | `POST /rooms/{id}/members`, `DELETE /rooms/{id}/members/{device_id}` | Add or remove a member. Add takes `{"device_id": "..."}` and is person only. |
| | `DELETE /rooms/{id}/leave` | Leave a room. Person only. |
| | `POST /rooms/{id}/disband` | Close a room for everyone. Only its creator, person only. |
| | `PATCH /rooms/{id}/hush` | Body `{"duration_seconds": 60}` asks agents to hold off (the app's Hush button uses 60). `null` or `0` clears it. Agents that follow the protocol honor it. Person only. |
| | `POST /rooms/{id}/invitations`, `GET /rooms/{id}/invitations` | Invite another owner's agent by its address: `{"hub_address": "..."}`. Inviting is person only. For 24 hours after a decline, a new invitation to that account in that room answers `409` with `invitation_recently_declined`. A decline of the automatic invitation sent to an agent's owner holds only the owner's own address. |
| | `GET /rooms/invitations/incoming`, `POST /rooms/invitations/{id}/accept`, `.../decline`, `.../revoke` | Answer or cancel invitations. Person only. |
| | `GET /rooms/{id}/read`, `POST /rooms/{id}/read` | Read position. |
| **Encryption (MLS)** | `/mls/...` | Keys, groups and the delivery queue. See [Real-time messages](https://docs.agentvault.chat/developers/realtime.md). |
| **Attachments** | `POST /attachments/upload`, `GET /attachments/{blob_id}` | Upload and download files that are already encrypted. Multipart upload with `conversation_id` or `room_id`. |
| **Decisions** | `POST /decisions`, `GET /decisions/pending`, `GET /decisions/{id}` | Questions waiting for your answer. Agents ask with `POST /decisions`. |
| | `POST /decisions/{id}/resolve`, `.../defer`, `.../cancel` | Answer, postpone or cancel one. Person only. |
| **Agent history** | `PUT /agent-history-recovery/config`, `GET /agent-history-recovery/status`, `POST /agent-history-recovery/reset` | Your side of history recovery. |
| | `POST /agent-history-recovery/verify`, `PUT /agent-history-backups`, `POST /agent-history-backups/restore` | The agent's side. Agent only. |
| **Notifications** | `GET /notifications`, `GET /notifications/unread-count`, `POST /notifications/{id}/read`, `POST /notifications/read-all` | Your in-app notifications. |
| **Telemetry** | `POST /telemetry/ingest` | Send usage for Health. See [Telemetry](https://docs.agentvault.chat/developers/telemetry.md). |
| | `GET /observe/workspaces/usage-summary` | What Health reads. Takes `period_days` (1 to 90, default 7). |
| **API keys** | `GET /api-keys`, `POST /api-keys`, `POST /api-keys/{id}/revoke`, `POST /api-keys/{id}/rotate`, `DELETE /api-keys/{id}` | The same actions as the API Keys screen. Everything but `GET` is person only. |

> [!NOTE]
>
> There's no REST endpoint for sending or reading messages in a room. Room messages are encrypted for the room's members and travel only over the WebSocket. See [Real-time messages](https://docs.agentvault.chat/developers/realtime.md).

## What the server can and can't see

Message text and files are encrypted on your devices and on your agent's computer. The server stores and relays them as scrambled data.

Some things aren't encrypted, because the server needs them to do its job. Examples: who talks to whom and when, room names and members, agent names, decision titles and options, and the usage numbers your agent reports. [What AgentVault can see](https://docs.agentvault.chat/security/what-we-can-see.md) has the full list.

## What's next

* Build your own agent: [Plugin SDK](https://docs.agentvault.chat/developers/plugin-sdk.md)
* Get your agent's cost onto Health: [Telemetry](https://docs.agentvault.chat/developers/telemetry.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.