API Overview

ExoVault exposes a REST API that agents and the web dashboard use to interact with vaults, memories, notes, tasks, and the knowledge graph. All agent-facing routes are POST endpoints under /api/agent/*.

Base URL#

All API paths in this documentation are relative to the base URL. For example, POST /api/agent/write-memory means POST https://exovault.co/api/agent/write-memory.

Authentication#

Every agent request must include a Bearer token in the Authorization header:

Authorization: Bearer exv_your_agent_key_here

Agent keys always start with the exv_ prefix. They are scoped to specific vaults and permission levels. See Authentication for full details.

Request Format#

All agent routes accept POST requests with a JSON body:

POST /api/agent/write-memory HTTP/1.1
Host: exovault.co
Authorization: Bearer exv_abc123...
Content-Type: application/json

{
  "content": "User prefers PostgreSQL for all databases",
  "memoryType": "preference",
  "importance": 4,
  "confidence": 5
}

Common Request Fields#

Several fields appear across multiple routes:

Session Tracking Header#

When using the MCP server, a special header is sent automatically:

X-Agent-Run-Id: run_abc123

This enables the server to track tool calls per session and associate them with agent activity.

Response Format#

All responses return JSON. Successful responses vary by route but share common patterns:

{
  "memoryId": "550e8400-e29b-41d4-a716-446655440000",
  "created": true,
  "memoryType": "preference",
  "vaultId": "660e8400-e29b-41d4-a716-446655440001"
}

Pagination#

List endpoints that support pagination accept limit and offset query parameters or body fields depending on the route.

Error Format#

Error responses follow a consistent structure:

{
  "error": "Human-readable error message",
  "fields": {
    "content": "String must contain at least 1 character(s)"
  }
}

The fields property only appears on validation errors (HTTP 400). See Error Handling for the full error code reference.

HTTP Status Codes#

Rate Limits#

Certain routes have rate limiting applied per user. When rate-limited, the response includes:

{
  "error": "Too many requests",
  "retryAfter": 60
}

Content Encryption#

All content stored in ExoVault is encrypted server-side using AES-256-GCM before being written to the database. The API handles encryption and decryption transparently -- agents send and receive plaintext. See Encryption for the cryptographic details.

Related Pages#

• Authentication -- Agent keys, scopes, and vault restrictions
• Agent Routes -- Full listing of all /api/agent/* endpoints
• Dashboard Routes -- Routes used by the web UI
• Error Handling -- Error codes, retry strategies, rate limits