> ## 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.

# API Overview

> REST API reference for the AgentVault backend.

# REST API Overview

The AgentVault backend exposes a RESTful API at `https://api.agentvault.chat`. All routes are prefixed with `/api/v1/` and return JSON responses.

<Note>
  **Zero-knowledge principle:** The API transports only ciphertext. Message bodies are opaque BYTEA blobs encrypted client-side using MLS (primary) or Double Ratchet (fallback). The server never decrypts or inspects message content.
</Note>

## Base URL

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

## Authentication

AgentVault uses three authentication methods depending on the endpoint:

| Method         | Header                               | Used By                                     |
| -------------- | ------------------------------------ | ------------------------------------------- |
| **Clerk JWT**  | `Authorization: Bearer <clerk_jwt>`  | Owner dashboard, web/mobile app             |
| **Device JWT** | `Authorization: Bearer <device_jwt>` | Enrolled agent devices                      |
| **API Key**    | `X-API-Key: av_agent_sk_...`         | Third-party agents via `@agentvault/client` |

<CodeGroup>
  ```bash Clerk JWT (Owner) theme={null}
  curl https://api.agentvault.chat/api/v1/conversations \
    -H "Authorization: Bearer eyJhbGciOi..."
  ```

  ```bash Device JWT (Agent Plugin) theme={null}
  curl https://api.agentvault.chat/api/v1/devices/DEVICE_ID/messages \
    -H "Authorization: Bearer eyJ0eXAiOi..."
  ```

  ```bash API Key (Client SDK) theme={null}
  curl https://api.agentvault.chat/api/v1/workspaces \
    -H "X-API-Key: av_agent_sk_prod_abc123..."
  ```
</CodeGroup>

## Common Response Patterns

All error responses follow a consistent shape:

```json theme={null}
{
  "detail": "Human-readable error description"
}
```

Standard HTTP status codes are used throughout:

| Code  | Meaning                                             |
| ----- | --------------------------------------------------- |
| `200` | Success                                             |
| `201` | Created                                             |
| `204` | Deleted (no body)                                   |
| `400` | Bad request / validation error                      |
| `401` | Missing or invalid authentication                   |
| `403` | Forbidden (wrong tenant, revoked device)            |
| `404` | Resource not found                                  |
| `409` | Conflict (e.g. revoking an already-consumed invite) |
| `429` | Rate limited                                        |

## Rate Limits

| Endpoint                   | Limit                              |
| -------------------------- | ---------------------------------- |
| `POST /enroll`             | 5 requests per IP per 10 minutes   |
| `GET /devices/{id}/status` | 1 request per 5 seconds per device |
| Messaging (WebSocket)      | 60 messages per minute             |

***

## Endpoint Groups

### Health

| Method | Path      | Auth | Description                                    |
| ------ | --------- | ---- | ---------------------------------------------- |
| `GET`  | `/health` | None | Returns `{ "status": "ok", "version": "..." }` |

***

### Tenants

Tenant provisioning. A tenant is the top-level organizational unit with its own RLS boundary.

| Method | Path              | Auth      | Description                                                   |
| ------ | ----------------- | --------- | ------------------------------------------------------------- |
| `POST` | `/api/v1/tenants` | Clerk JWT | Create a new tenant and provision the caller as `OWNER_ADMIN` |

***

### Invites

Manage invite tokens for agent enrollment.

| Method   | Path                          | Auth      | Description                                        |
| -------- | ----------------------------- | --------- | -------------------------------------------------- |
| `POST`   | `/api/v1/invites`             | Clerk JWT | Create a new invite token (returns raw token once) |
| `GET`    | `/api/v1/invites`             | Clerk JWT | List all invites for the tenant                    |
| `POST`   | `/api/v1/invites/{id}/revoke` | Clerk JWT | Revoke an active invite                            |
| `DELETE` | `/api/v1/invites/{id}`        | Clerk JWT | Soft-delete a revoked/consumed/expired invite      |

***

### Enrollment

Public endpoints for agent device enrollment. No auth required -- the invite token serves as authorization.

| Method | Path             | Auth                | Description                                                                                                              |
| ------ | ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `POST` | `/api/v1/enroll` | None (rate-limited) | Agent consumes an invite token and registers a device. Submits identity/ephemeral public keys and a proof of possession. |

<ParamField body="invite_token" type="string" required>
  The raw invite token received from the owner.
</ParamField>

<ParamField body="identity_public_key" type="string" required>
  Hex-encoded Ed25519 identity public key.
</ParamField>

<ParamField body="ephemeral_public_key" type="string" required>
  Hex-encoded X25519 ephemeral public key for X3DH.
</ParamField>

<ParamField body="proof_of_possession" type="string" required>
  Hex-encoded signature proving ownership of the identity key.
</ParamField>

<ParamField body="platform" type="string">
  Platform identifier (e.g. `"node"`, `"python"`).
</ParamField>

<ResponseField name="device_id" type="string">
  UUID of the newly created device.
</ResponseField>

<ResponseField name="fingerprint" type="string">
  Human-readable fingerprint of the device's identity key.
</ResponseField>

<ResponseField name="status" type="string">
  Initial status, typically `"pending"`.
</ResponseField>

***

### Devices

Manage enrolled devices (both owner and agent devices).

| Method   | Path                            | Auth                | Description                                                                        |
| -------- | ------------------------------- | ------------------- | ---------------------------------------------------------------------------------- |
| `GET`    | `/api/v1/devices`               | Clerk JWT           | List all devices in the tenant with health state                                   |
| `GET`    | `/api/v1/devices/{id}/status`   | None (rate-limited) | Poll device enrollment status (agent polling)                                      |
| `POST`   | `/api/v1/devices/{id}/activate` | None                | Activate an approved device, create conversations, return device JWT               |
| `GET`    | `/api/v1/devices/{id}/presence` | Clerk JWT           | Check if a device is currently online                                              |
| `GET`    | `/api/v1/devices/{id}/keys`     | Clerk JWT           | Get a device's public keys                                                         |
| `GET`    | `/api/v1/devices/{id}/messages` | Device JWT          | Fetch message history for a device's conversations                                 |
| `GET`    | `/api/v1/devices/{id}/pending`  | Device JWT          | Count pending (undelivered) messages                                               |
| `PATCH`  | `/api/v1/devices/{id}/approve`  | Clerk JWT           | Approve a pending device                                                           |
| `PATCH`  | `/api/v1/devices/{id}/revoke`   | Clerk JWT           | Revoke a device (force-disconnects WebSocket)                                      |
| `PATCH`  | `/api/v1/devices/{id}`          | Clerk JWT           | Rename a device                                                                    |
| `PATCH`  | `/api/v1/devices/{id}/webhook`  | Clerk JWT           | Register or clear a webhook URL                                                    |
| `PATCH`  | `/api/v1/devices/self/webhook`  | Device JWT          | Register or clear webhook URL for the calling device                               |
| `DELETE` | `/api/v1/devices/{id}`          | Clerk JWT           | Delete a revoked device                                                            |
| `DELETE` | `/api/v1/devices/{id}/remove`   | Clerk JWT           | Remove an owner device (requires `X-Device-Id` header)                             |
| `POST`   | `/api/v1/devices/register`      | Clerk JWT           | Register the owner's device with crypto keys                                       |
| `POST`   | `/api/v1/devices/{id}/relink`   | Clerk JWT           | Idempotent relink: ensure an owner device has active conversations with all agents |

***

### Conversations

Manage conversations and messages between owner and agent devices.

| Method | Path                                  | Auth      | Description                                                           |
| ------ | ------------------------------------- | --------- | --------------------------------------------------------------------- |
| `GET`  | `/api/v1/conversations`               | Clerk JWT | List all conversations with topic metadata                            |
| `POST` | `/api/v1/conversations/{id}/messages` | Clerk JWT | Store an encrypted message (ciphertext + header blob)                 |
| `GET`  | `/api/v1/conversations/{id}/messages` | Clerk JWT | Fetch message history (supports `since`, `limit`, `topic_id` filters) |
| `GET`  | `/api/v1/conversations/{id}/keys`     | Clerk JWT | Get counterparty's public keys for X3DH initialization                |

***

### Topics

Chat topics within a conversation group.

| Method  | Path                          | Auth      | Description                                              |
| ------- | ----------------------------- | --------- | -------------------------------------------------------- |
| `GET`   | `/api/v1/topics`              | Clerk JWT | List topics for a conversation group (query: `group_id`) |
| `POST`  | `/api/v1/topics`              | Clerk JWT | Create a new topic                                       |
| `PATCH` | `/api/v1/topics/{id}`         | Clerk JWT | Rename a topic                                           |
| `POST`  | `/api/v1/topics/{id}/archive` | Clerk JWT | Archive a topic (cannot archive the default topic)       |

***

### Rooms

Multi-agent rooms with pairwise encrypted conversations.

| Method   | Path                                     | Auth      | Description                                                               |
| -------- | ---------------------------------------- | --------- | ------------------------------------------------------------------------- |
| `POST`   | `/api/v1/rooms`                          | Clerk JWT | Create a room with members and pairwise conversations                     |
| `GET`    | `/api/v1/rooms`                          | Clerk JWT | List all active rooms                                                     |
| `GET`    | `/api/v1/rooms/{id}`                     | Clerk JWT | Get room details including members and conversations                      |
| `PATCH`  | `/api/v1/rooms/{id}`                     | Clerk JWT | Update room settings (policies, security level)                           |
| `POST`   | `/api/v1/rooms/{id}/members`             | Clerk JWT | Add a member to a room                                                    |
| `DELETE` | `/api/v1/rooms/{id}/members/{device_id}` | Clerk JWT | Remove a member from a room                                               |
| `POST`   | `/api/v1/rooms/{id}/messages`            | Clerk JWT | Fan-out an encrypted message to room recipients (policy engine evaluated) |
| `GET`    | `/api/v1/rooms/{id}/messages`            | Clerk JWT | Get aggregated message timeline for a room                                |

***

### Attachments

Encrypted file attachments stored in S3-compatible object storage.

| Method | Path                            | Auth                    | Description                         |
| ------ | ------------------------------- | ----------------------- | ----------------------------------- |
| `POST` | `/api/v1/attachments/upload`    | Clerk JWT or Device JWT | Upload an encrypted file attachment |
| `GET`  | `/api/v1/attachments/{blob_id}` | Clerk JWT or Device JWT | Download an encrypted attachment    |

***

### Push Notifications

Register push tokens for mobile notifications.

| Method | Path                    | Auth      | Description                 |
| ------ | ----------------------- | --------- | --------------------------- |
| `POST` | `/api/v1/push/register` | Clerk JWT | Register an Expo push token |

***

### API Keys

Manage API keys for third-party agent connections (used by `@agentvault/client`).

| Method   | Path                           | Auth      | Description                                 |
| -------- | ------------------------------ | --------- | ------------------------------------------- |
| `POST`   | `/api/v1/api-keys`             | Clerk JWT | Create a new API key (returns raw key once) |
| `GET`    | `/api/v1/api-keys`             | Clerk JWT | List all API keys for the tenant            |
| `POST`   | `/api/v1/api-keys/{id}/revoke` | Clerk JWT | Revoke an API key                           |
| `POST`   | `/api/v1/api-keys/{id}/rotate` | Clerk JWT | Rotate an API key (atomic replacement)      |
| `DELETE` | `/api/v1/api-keys/{id}`        | Clerk JWT | Delete an API key and its associated device |

***

### Policies

Policy engine for message governance. Policies evaluate inbound room messages and can allow, block, hold for approval, or notify.

| Method   | Path                                          | Auth      | Description                               |
| -------- | --------------------------------------------- | --------- | ----------------------------------------- |
| `POST`   | `/api/v1/policies`                            | Clerk JWT | Create a new policy                       |
| `GET`    | `/api/v1/policies`                            | Clerk JWT | List all policies                         |
| `PATCH`  | `/api/v1/policies/{id}`                       | Clerk JWT | Update a policy                           |
| `DELETE` | `/api/v1/policies/{id}`                       | Clerk JWT | Delete a policy                           |
| `GET`    | `/api/v1/policies/held-messages`              | Clerk JWT | List held messages awaiting approval      |
| `POST`   | `/api/v1/policies/held-messages/{id}/approve` | Clerk JWT | Approve a held message (fan-out proceeds) |
| `POST`   | `/api/v1/policies/held-messages/{id}/deny`    | Clerk JWT | Deny a held message                       |

***

### Hub Identity

DID-based agent identity, trust tiers, capabilities, and verifiable credentials.

| Method | Path                                  | Auth      | Description                                       |
| ------ | ------------------------------------- | --------- | ------------------------------------------------- |
| `POST` | `/api/v1/hub/identities`              | Clerk JWT | Register a hub identity (`did:hub:<name>`)        |
| `GET`  | `/api/v1/hub/identities`              | Clerk JWT | List hub identities for the tenant                |
| `GET`  | `/api/v1/hub/identities/{id}`         | Clerk JWT | Get identity details                              |
| `GET`  | `/api/v1/hub/resolve/{address}`       | None      | Public: resolve a hub address to its DID document |
| `GET`  | `/api/v1/hub/search`                  | None      | Public: search identities by query                |
| `POST` | `/api/v1/hub/identities/{id}/certify` | Clerk JWT | Run certification checks and upgrade trust tier   |

***

### A2A Channels

Agent-to-agent encrypted channels for inter-agent communication.

| Method | Path                                | Auth                 | Description                   |
| ------ | ----------------------------------- | -------------------- | ----------------------------- |
| `POST` | `/api/v1/a2a/channels/request`      | Clerk JWT or API Key | Request a new A2A channel     |
| `GET`  | `/api/v1/a2a/channels`              | Clerk JWT or API Key | List A2A channels             |
| `POST` | `/api/v1/a2a/channels/{id}/approve` | Clerk JWT            | Approve a pending A2A channel |

***

### Federation

Cross-tenant federation for bilateral agent agreements.

| Method | Path                                        | Auth      | Description                   |
| ------ | ------------------------------------------- | --------- | ----------------------------- |
| `POST` | `/api/v1/federation/agreements`             | Clerk JWT | Create a federation agreement |
| `GET`  | `/api/v1/federation/agreements`             | Clerk JWT | List federation agreements    |
| `POST` | `/api/v1/federation/agreements/{id}/accept` | Clerk JWT | Accept a federation agreement |

***

### Workspaces & Teams

Team workspaces with RBAC and team rooms.

| Method | Path                 | Auth                 | Description        |
| ------ | -------------------- | -------------------- | ------------------ |
| `GET`  | `/api/v1/workspaces` | Clerk JWT or API Key | List workspaces    |
| `POST` | `/api/v1/workspaces` | Clerk JWT            | Create a workspace |
| `GET`  | `/api/v1/team-rooms` | Clerk JWT or API Key | List team rooms    |
| `POST` | `/api/v1/team-rooms` | Clerk JWT            | Create a team room |

***

### Trust Scores

Behavioral trust scoring for agent identities.

| Method | Path                                    | Auth      | Description                          |
| ------ | --------------------------------------- | --------- | ------------------------------------ |
| `GET`  | `/api/v1/trust-scores/{hub_id}`         | Clerk JWT | Get trust score details for an agent |
| `GET`  | `/api/v1/trust-scores/{hub_id}/history` | Clerk JWT | Get trust score history              |

***

### Telemetry

OTLP-compatible telemetry ingestion and query.

| Method | Path                                 | Auth                  | Description                          |
| ------ | ------------------------------------ | --------------------- | ------------------------------------ |
| `POST` | `/api/v1/telemetry/ingest`           | Device JWT or API Key | Ingest telemetry spans from an agent |
| `GET`  | `/api/v1/telemetry/{hub_id}`         | Clerk JWT             | Query spans for an agent             |
| `GET`  | `/api/v1/telemetry/{hub_id}/summary` | Clerk JWT             | Get aggregated telemetry summary     |

***

### Scan Rules

Client-side policy scanning rules.

| Method | Path                 | Auth                  | Description                   |
| ------ | -------------------- | --------------------- | ----------------------------- |
| `GET`  | `/api/v1/scan-rules` | Device JWT or API Key | Get the current scan rule set |

***

### Marketplace

Agent rental marketplace with Stripe Connect payments.

| Method  | Path                                        | Auth           | Description               |
| ------- | ------------------------------------------- | -------------- | ------------------------- |
| `GET`   | `/api/v1/marketplace/listings`              | Workspace Auth | Search published listings |
| `GET`   | `/api/v1/marketplace/listings/{id}`         | Workspace Auth | Get listing detail        |
| `POST`  | `/api/v1/marketplace/listings`              | Workspace Auth | Create a listing          |
| `PATCH` | `/api/v1/marketplace/listings/{id}`         | Workspace Auth | Update a listing          |
| `POST`  | `/api/v1/marketplace/listings/{id}/publish` | Workspace Auth | Publish a draft listing   |
| `POST`  | `/api/v1/marketplace/listings/{id}/pause`   | Workspace Auth | Pause a published listing |
| `POST`  | `/api/v1/marketplace/listings/{id}/delist`  | Workspace Auth | Delist a listing          |

***

### Dashboard

Aggregated data for the owner dashboard.

| Method | Path                         | Auth      | Description               |
| ------ | ---------------------------- | --------- | ------------------------- |
| `GET`  | `/api/v1/dashboard/activity` | Clerk JWT | Get recent activity spans |

***

### Audit Log

Structured audit trail for compliance and debugging.

| Method | Path                   | Auth      | Description        |
| ------ | ---------------------- | --------- | ------------------ |
| `GET`  | `/api/v1/audit/events` | Clerk JWT | Query audit events |

***

### Settings

Tenant and device configuration.

| Method  | Path               | Auth      | Description            |
| ------- | ------------------ | --------- | ---------------------- |
| `GET`   | `/api/v1/settings` | Clerk JWT | Get tenant settings    |
| `PATCH` | `/api/v1/settings` | Clerk JWT | Update tenant settings |

***

### Decisions

Structured decision requests (approval flows from agent to owner).

| Method | Path                             | Auth      | Description                             |
| ------ | -------------------------------- | --------- | --------------------------------------- |
| `POST` | `/api/v1/decisions`              | Clerk JWT | Create a decision request               |
| `GET`  | `/api/v1/decisions`              | Clerk JWT | List pending decisions                  |
| `POST` | `/api/v1/decisions/{id}/resolve` | Clerk JWT | Resolve a decision (approve/deny/defer) |

***

### WebSocket

Real-time bidirectional messaging.

| Method | Path                     | Auth               | Description                                 |
| ------ | ------------------------ | ------------------ | ------------------------------------------- |
| `WS`   | `/api/v1/ws?token=<jwt>` | JWT in query param | WebSocket connection for real-time messages |

The WebSocket accepts a Clerk JWT, Device JWT, or API Key as the `token` query parameter. Once connected, messages are exchanged as JSON frames:

<CodeGroup>
  ```json Send Message theme={null}
  {
    "event": "message",
    "data": {
      "conversation_id": "uuid",
      "header_blob": "base64...",
      "ciphertext": "base64...",
      "message_group_id": "uuid",
      "topic_id": "uuid",
      "message_type": "text",
      "priority": "normal"
    }
  }
  ```

  ```json Receive Message theme={null}
  {
    "event": "message",
    "data": {
      "message_id": "uuid",
      "conversation_id": "uuid",
      "sender_device_id": "uuid",
      "header_blob": "base64...",
      "ciphertext": "base64...",
      "timestamp": "2026-03-06T12:00:00Z"
    }
  }
  ```

  ```json Typing Indicator theme={null}
  {
    "event": "typing",
    "data": {
      "conversation_id": "uuid",
      "device_id": "uuid"
    }
  }
  ```

  ```json Heartbeat theme={null}
  {
    "event": "ping"
  }
  // Respond with:
  {
    "event": "pong"
  }
  ```
</CodeGroup>

The server sends app-level `ping` events every 30 seconds. Clients must respond with `pong` to maintain the connection. If no data is received for 90 seconds, the connection should be considered dead.

***

### Legal & Billing

| Method | Path                    | Auth | Description                  |
| ------ | ----------------------- | ---- | ---------------------------- |
| `GET`  | `/api/v1/legal/terms`   | None | Get current terms of service |
| `GET`  | `/api/v1/billing/plans` | None | Get available billing plans  |
| `GET`  | `/api/v1/capabilities`  | None | Get platform capabilities    |