Memory API Reference

RESTful API for memory CRUD operations.

Authentication

Both header formats are supported:

# Option 1: x-sovant-api-key (preferred)
-H "x-sovant-api-key: sk_live_your_api_key"

# Option 2: Authorization Bearer
-H "Authorization: Bearer sk_live_your_api_key"

Create Memory

POST /api/v1/memory

curl -X POST https://sovant.ai/api/v1/memory \
  -H "x-sovant-api-key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers dark mode interfaces",
    "type": "preference",
    "tags": ["ui", "settings"],
    "metadata": {"confidence": 0.95}
  }'

Response:

{
  "id": "mem_abc123",
  "content": "User prefers dark mode interfaces",
  "type": "preference",
  "tags": ["ui", "settings"],
  "metadata": {"confidence": 0.95},
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "ok": true
}

Get Memory

GET /api/v1/memories/{id}

curl https://sovant.ai/api/v1/memories/mem_abc123 \
  -H "Authorization: Bearer sk_live_your_api_key"

Update Memory (Partial)

PATCH /api/v1/memories/{id}

curl -X PATCH https://sovant.ai/api/v1/memories/mem_abc123 \
  -H "x-sovant-api-key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["ui", "settings", "theme"],
    "metadata": {"confidence": 1.0, "source": "explicit"}
  }'

Replace Memory (Full)

PUT /api/v1/memories/{id}

curl -X PUT https://sovant.ai/api/v1/memories/mem_abc123 \
  -H "x-sovant-api-key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User strongly prefers dark mode",
    "type": "preference",
    "tags": ["ui", "theme"]
  }'

Delete Memory

DELETE /api/v1/memories/{id}

curl -X DELETE https://sovant.ai/api/v1/memories/mem_abc123 \
  -H "Authorization: Bearer sk_live_your_api_key"

Response:

{
  "ok": true
}

List Memories

GET /api/v1/memory

Query parameters:

limit - Max results (default: 20, max: 100)
offset - Pagination offset
type - Filter by type
tags - Filter by tags (comma-separated)
thread_id - Filter by thread
is_archived - Include/exclude archived

curl -G "https://sovant.ai/api/v1/memory" \
  -H "x-sovant-api-key: sk_live_your_api_key" \
  --data-urlencode "type=preference" \
  --data-urlencode "tags=ui,settings" \
  --data-urlencode "limit=10"

Response:

{
  "memories": [...],
  "total": 42,
  "limit": 10,
  "offset": 0,
  "has_more": true
}