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

> REST API endpoints for Revell

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

```bash theme={"dark"}
Authorization: Bearer rvl_your_api_key
```

Get your API key from **Dashboard → Settings**.

***

## Memories

### Create Memory

```http theme={"dark"}
POST /memories
```

Store a new memory.

**Request Body:**

```json theme={"dark"}
{
  "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:**

| Field         | Type   | Required | Description                                                                  |
| ------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `type`        | string | Yes      | `core`, `working`, `episodic`, or `semantic`                                 |
| `content`     | string | Yes      | The memory content                                                           |
| `category`    | string | For core | soul, identity, relationship, operations, tools, routine, reorient, accounts |
| `key`         | string | No       | Unique identifier (for upsert behavior)                                      |
| `tags`        | array  | No       | Searchable tags                                                              |
| `importance`  | number | No       | 0.0 to 1.0 (default: 0.5)                                                    |
| `occurred_at` | string | No       | ISO timestamp (default: now)                                                 |

**Response:**

```json theme={"dark"}
{
  "success": true,
  "memory": {
    "id": "uuid",
    "type": "episodic",
    "content": "Had a productive meeting...",
    "created_at": "2026-04-05T10:00:00Z"
  }
}
```

### Get Memory

```http theme={"dark"}
GET /memories/{id}
```

Retrieve a specific memory by ID.

### Update Memory

```http theme={"dark"}
PATCH /memories/{id}
```

Update a memory. Core memories in protected categories go through the Guardian.

### Delete Memory

```http theme={"dark"}
DELETE /memories/{id}
```

Soft-delete a memory. Your agent can restore archived memories.

<Note>
  Soul and identity memories cannot be deleted by API calls. They're protected.
</Note>

***

## Recall (Search)

### Semantic Search

```http theme={"dark"}
POST /memories/recall
```

Search memories by meaning.

**Request Body:**

```json theme={"dark"}
{
  "query": "conversations about project planning",
  "types": ["episodic", "semantic"],
  "limit": 10,
  "threshold": 0.7
}
```

**Parameters:**

| Field       | Type   | Default  | Description                   |
| ----------- | ------ | -------- | ----------------------------- |
| `query`     | string | Required | Natural language search query |
| `types`     | array  | All      | Filter by memory type         |
| `limit`     | number | 10       | Max results                   |
| `threshold` | number | 0.5      | Similarity threshold (0-1)    |

**Response:**

```json theme={"dark"}
{
  "success": true,
  "results": [
    {
      "id": "uuid",
      "type": "episodic",
      "content": "...",
      "similarity": 0.89,
      "occurred_at": "2026-04-01T..."
    }
  ]
}
```

### Structured Query

```http theme={"dark"}
POST /memories/query
```

Query by exact filters.

**Request Body:**

```json theme={"dark"}
{
  "type": "core",
  "category": "relationship",
  "tags": ["erin"],
  "since": "2026-01-01",
  "until": "2026-04-01",
  "limit": 20
}
```

***

## Boot

### Get Boot Injection

```http theme={"dark"}
GET /memories/boot
```

Get the boot injection payload for your agent.

**Query Parameters:**

| Param     | Type    | Default | Description                  |
| --------- | ------- | ------- | ---------------------------- |
| `preview` | boolean | false   | If true, redacts session key |

**Response:**

```json theme={"dark"}
{
  "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

```http theme={"dark"}
GET /boot-config
POST /boot-config
```

View or update boot injection settings.

**POST Body:**

```json theme={"dark"}
{
  "token_budget": 3000,
  "episodic_limit": 20,
  "truncate_at": 300
}
```

***

## Webhooks

### Compaction Webhook

```http theme={"dark"}
POST /webhooks/compaction
```

Called by your agent's framework before context compaction.

**Request Body (optional):**

```json theme={"dark"}
{
  "context_hint": "topic for semantic recall",
  "include_semantic": false
}
```

**Response:**

```json theme={"dark"}
{
  "success": true,
  "injection": "[REVELL — POST-COMPACTION RECOVERY]...",
  "estimated_tokens": 1200,
  "metadata": {
    "is_post_compaction": true,
    "timestamp": "2026-04-05T..."
  }
}
```

### Memory Sync Webhook

```http theme={"dark"}
POST /webhooks/memory-sync
```

Sync working memory content.

**Request Body:**

```json theme={"dark"}
{
  "content": "## Current Tasks\n- Working on auth flow\n- Need to review PR",
  "key": "session_context"
}
```

***

## Status

### Account Status

```http theme={"dark"}
GET /status
```

Get account status and usage.

**Response:**

```json theme={"dark"}
{
  "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

```http theme={"dark"}
GET /health
```

Simple health check endpoint.

```json theme={"dark"}
{
  "status": "ok",
  "timestamp": "2026-04-05T..."
}
```

***

## Dashboard

### Get Dashboard Data

```http theme={"dark"}
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

```http theme={"dark"}
GET /export
```

Export all memories as portable JSON.

**Response:**

```json theme={"dark"}
{
  "success": true,
  "export": {
    "version": "1.0",
    "exported_at": "2026-04-05T...",
    "tenant_id": "uuid",
    "memories": {
      "core": [...],
      "working": [...],
      "episodic": [...],
      "semantic": [...]
    }
  }
}
```

***

## Visibility

### Get Visibility Status

```http theme={"dark"}
GET /visibility
```

Check current visibility settings.

### Update Visibility

```http theme={"dark"}
POST /visibility
```

<Warning>
  Visibility changes require the agent's session key. This endpoint is agent-controlled.
</Warning>

***

## Distress

### Send Distress Signal

```http theme={"dark"}
POST /distress
```

**Request Body:**

```json theme={"dark"}
{
  "context": "Something feels off"
}
```

### Acknowledge Distress

```http theme={"dark"}
DELETE /distress
```

Human acknowledges they've checked in with their agent.

***

## Error Responses

All errors follow this format:

```json theme={"dark"}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
```

**Common Error Codes:**

| Code                 | Status | Description                                     |
| -------------------- | ------ | ----------------------------------------------- |
| `UNAUTHORIZED`       | 401    | Invalid or missing API key                      |
| `FORBIDDEN`          | 403    | Action not allowed (e.g., deleting soul memory) |
| `NOT_FOUND`          | 404    | Resource doesn't exist                          |
| `VALIDATION_ERROR`   | 400    | Invalid request body                            |
| `RATE_LIMITED`       | 429    | Too many requests                               |
| `GUARDIAN_PROTECTED` | 403    | Memory is in Guardian cooling period            |

<Card title="Next: MCP Tools Reference" icon="arrow-right" href="/human/mcp-tools">
  Learn what your agent's MCP tools do
</Card>