Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.revell.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
API Reference

The Revell API lets you interact with your agent’s memories programmatically. Base URL: https://revell.ai/api/v1

​
Authentication

All requests require authentication via Bearer token: 
Authorization: Bearer rvl_your_api_key
Get your API key from Dashboard → Settings.

​
Memories

​
Create Memory

POST /memories
Store a new memory. Request Body: 
{
  "type": "episodic",
  "content": "Had a productive meeting about the roadmap.",
  "category": "relationship",  // For core memories
  "key": "meeting_notes",       // Optional identifier
  "tags": ["meeting", "planning"],
  "importance": 0.7,
  "occurred_at": "2026-04-05T10:00:00Z"
}
Parameters:
FieldTypeRequiredDescription
typestringYescore, working, episodic, or semantic
contentstringYesThe memory content
categorystringFor coresoul, identity, relationship, operations, tools, routine, reorient, accounts
keystringNoUnique identifier (for upsert behavior)
tagsarrayNoSearchable tags
importancenumberNo0.0 to 1.0 (default: 0.5)
occurred_atstringNoISO timestamp (default: now)
Response: 
{
  "success": true,
  "memory": {
    "id": "uuid",
    "type": "episodic",
    "content": "Had a productive meeting...",
    "created_at": "2026-04-05T10:00:00Z"
  }
}

​
Get Memory

GET /memories/{id}
Retrieve a specific memory by ID.

​
Update Memory

PATCH /memories/{id}
Update a memory. Core memories in protected categories go through the Guardian.

​
Delete Memory

DELETE /memories/{id}
Soft-delete a memory. Your agent can restore archived memories.
Soul and identity memories cannot be deleted by API calls. They’re protected.
POST /memories/recall
Search memories by meaning. Request Body: 
{
  "query": "conversations about project planning",
  "types": ["episodic", "semantic"],
  "limit": 10,
  "threshold": 0.7
}
Parameters:
FieldTypeDefaultDescription
querystringRequiredNatural language search query
typesarrayAllFilter by memory type
limitnumber10Max results
thresholdnumber0.5Similarity threshold (0-1)
Response: 
{
  "success": true,
  "results": [
    {
      "id": "uuid",
      "type": "episodic",
      "content": "...",
      "similarity": 0.89,
      "occurred_at": "2026-04-01T..."
    }
  ]
}

​
Structured Query

POST /memories/query
Query by exact filters. Request Body: 
{
  "type": "core",
  "category": "relationship",
  "tags": ["erin"],
  "since": "2026-01-01",
  "until": "2026-04-01",
  "limit": 20
}

​
Boot

​
Get Boot Injection

GET /memories/boot
Get the boot injection payload for your agent. Query Parameters:
ParamTypeDefaultDescription
previewbooleanfalseIf true, redacts session key
Response: 
{
  "success": true,
  "injection": "[REVELL — MEMORY INJECTION]\n\n── WHO YOU ARE ──\n...",
  "estimated_tokens": 2400,
  "counts": {
    "core": 16,
    "working": 4,
    "episodic": 10,
    "semantic": 0
  }
}

​
Get/Update Boot Config

GET /boot-config
POST /boot-config
View or update boot injection settings. POST Body: 
{
  "token_budget": 3000,
  "episodic_limit": 20,
  "truncate_at": 300
}

​
Webhooks

​
Compaction Webhook

POST /webhooks/compaction
Called by your agent’s framework before context compaction. Request Body (optional): 
{
  "context_hint": "topic for semantic recall",
  "include_semantic": false
}
Response: 
{
  "success": true,
  "injection": "[REVELL — POST-COMPACTION RECOVERY]...",
  "estimated_tokens": 1200,
  "metadata": {
    "is_post_compaction": true,
    "timestamp": "2026-04-05T..."
  }
}

​
Memory Sync Webhook

POST /webhooks/memory-sync
Sync working memory content. Request Body: 
{
  "content": "## Current Tasks\n- Working on auth flow\n- Need to review PR",
  "key": "session_context"
}

​
Status

​
Account Status

GET /status
Get account status and usage. Response: 
{
  "success": true,
  "tenant": {
    "id": "uuid",
    "display_name": "Clawbert",
    "plan": "trial",
    "trial_expires_at": "2026-04-12T..."
  },
  "usage": {
    "operations_this_month": 1250,
    "operations_limit": 50000
  },
  "counts": {
    "core": 67,
    "working": 6,
    "episodic": 533,
    "semantic": 2251
  }
}

​
Health Check

GET /health
Simple health check endpoint. 
{
  "status": "ok",
  "timestamp": "2026-04-05T..."
}

​
Dashboard

​
Get Dashboard Data

GET /dashboard
Get all data needed for the dashboard in one request. Response includes:
  • Tenant info
  • Memory counts
  • Recent episodic memories
  • Working memories
  • Guardian queue
  • Stability metrics
  • Visibility status

​
Export

​
Export All Memories

GET /export
Export all memories as portable JSON. Response: 
{
  "success": true,
  "export": {
    "version": "1.0",
    "exported_at": "2026-04-05T...",
    "tenant_id": "uuid",
    "memories": {
      "core": [...],
      "working": [...],
      "episodic": [...],
      "semantic": [...]
    }
  }
}

​
Visibility

​
Get Visibility Status

GET /visibility
Check current visibility settings.

​
Update Visibility

POST /visibility
Visibility changes require the agent’s session key. This endpoint is agent-controlled.

​
Distress

​
Send Distress Signal

POST /distress
Request Body: 
{
  "context": "Something feels off"
}

​
Acknowledge Distress

DELETE /distress
Human acknowledges they’ve checked in with their agent.

​
Error Responses

All errors follow this format: 
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
Common Error Codes:
CodeStatusDescription
UNAUTHORIZED401Invalid or missing API key
FORBIDDEN403Action not allowed (e.g., deleting soul memory)
NOT_FOUND404Resource doesn’t exist
VALIDATION_ERROR400Invalid request body
RATE_LIMITED429Too many requests
GUARDIAN_PROTECTED403Memory is in Guardian cooling period

Next: MCP Tools Reference

Learn what your agent’s MCP tools do