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.

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.

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`

curl https://api.agentvault.chat/api/v1/conversations \
  -H "Authorization: Bearer eyJhbGciOi..."

curl https://api.agentvault.chat/api/v1/devices/DEVICE_ID/messages \
  -H "Authorization: Bearer eyJ0eXAiOi..."

curl https://api.agentvault.chat/api/v1/workspaces \
  -H "X-API-Key: av_agent_sk_prod_abc123..."

Common Response Patterns

All error responses follow a consistent shape:

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

string

required

The raw invite token received from the owner.

string

required

Hex-encoded Ed25519 identity public key.

string

required

Hex-encoded X25519 ephemeral public key for X3DH.

string

required

Hex-encoded signature proving ownership of the identity key.

string

Platform identifier (e.g. "node", "python").

string

UUID of the newly created device.

string

Human-readable fingerprint of the device’s identity key.

string

Initial status, typically "pending".

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

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:

{
  "event": "message",
  "data": {
    "conversation_id": "uuid",
    "header_blob": "base64...",
    "ciphertext": "base64...",
    "message_group_id": "uuid",
    "topic_id": "uuid",
    "message_type": "text",
    "priority": "normal"
  }
}

{
  "event": "message",
  "data": {
    "message_id": "uuid",
    "conversation_id": "uuid",
    "sender_device_id": "uuid",
    "header_blob": "base64...",
    "ciphertext": "base64...",
    "timestamp": "2026-03-06T12:00:00Z"
  }
}

{
  "event": "typing",
  "data": {
    "conversation_id": "uuid",
    "device_id": "uuid"
  }
}

{
  "event": "ping"
}
// Respond with:
{
  "event": "pong"
}

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

​REST API Overview

​Base URL

​Authentication

​Common Response Patterns

​Rate Limits

​Endpoint Groups

​Health

​Tenants

​Invites

​Enrollment

​Devices

​Conversations

​Topics

​Rooms

​Attachments

​Push Notifications

​API Keys

​Policies

​Hub Identity

​A2A Channels

​Federation

​Workspaces & Teams

​Trust Scores

​Telemetry

​Scan Rules

​Marketplace

​Dashboard

​Audit Log

​Settings

​Decisions

​WebSocket

​Legal & Billing

REST API Overview

Base URL

Authentication

Common Response Patterns

Rate Limits

Endpoint Groups

Health

Tenants

Invites

Enrollment

Devices

Conversations

Topics

Rooms

Attachments

Push Notifications

API Keys

Policies

Hub Identity

A2A Channels

Federation

Workspaces & Teams

Trust Scores

Telemetry

Scan Rules

Marketplace

Dashboard

Audit Log

Settings

Decisions

WebSocket

Legal & Billing