> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loom.teamecho.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete REST API reference for loom.

The Loom REST API is served by FastAPI. Start the server with:

```bash theme={null}
loom serve --host 0.0.0.0 --port 8666
```

Base URL: `http://localhost:8666`

## Core

### Build Memory

<ParamField body="text" type="string" required>
  The text to process into memory.
</ParamField>

<ParamField body="session_id" type="string" required>
  The session identifier.
</ParamField>

```bash theme={null}
POST /api/build
```

```json theme={null}
{
  "text": "I am Alice, I love hiking.",
  "session_id": "alice"
}
```

### Chat

<ParamField body="message" type="string" required>
  The user's message.
</ParamField>

<ParamField body="session_id" type="string" required>
  The session identifier.
</ParamField>

```bash theme={null}
POST /api/chat
```

```json theme={null}
{
  "message": "What are my hobbies?",
  "session_id": "alice"
}
```

Response includes a `schema_updated` flag indicating if auto-update was triggered this round.

### Listen

<ParamField body="message" type="string" required>
  The user's message.
</ParamField>

<ParamField body="session_id" type="string" required>
  The session identifier.
</ParamField>

```bash theme={null}
POST /api/listen
```

```json theme={null}
{
  "message": "I just started learning piano.",
  "session_id": "alice"
}
```

Listen mode: accumulates history, runs the CM agent in build mode periodically (every `build_every_n_turns` turns), and recalls schema data every turn. Returns `reply`, `session_id`, and `turn_number`.

### Update Schema from Chat

<ParamField body="session_id" type="string" required>
  The session identifier.
</ParamField>

<ParamField body="rounds" type="integer">
  Number of recent chat rounds to process.
</ParamField>

```bash theme={null}
POST /api/update-schema-from-chat
```

```json theme={null}
{
  "session_id": "alice",
  "rounds": 5
}
```

## Configuration

### Get Build Every N Turns

```bash theme={null}
GET /api/config/build-every-n-turns
```

### Set Build Every N Turns

```bash theme={null}
PUT /api/config/build-every-n-turns
```

```json theme={null}
{
  "build_every_n_turns": 3
}
```

### Get Chatbot Context Rounds

```bash theme={null}
GET /api/config/chatbot-context-rounds
```

### Set Chatbot Context Rounds

```bash theme={null}
PUT /api/config/chatbot-context-rounds
```

```json theme={null}
{
  "context_rounds": 10
}
```

## Schemas

### List Schema Domains

```bash theme={null}
GET /api/schemas
```

### Get Schema Details

```bash theme={null}
GET /api/schemas/{name}
```

### Get Schema File Data

```bash theme={null}
GET /api/schemas/file-data/{schema_id}
```

Returns all domain data from a schema file — suitable for sidebar rendering.

### Recall All Schemas

```bash theme={null}
GET /api/schemas/recall-all
GET /api/schemas/recall-all?schema_id=default
```

Returns all schema data as formatted text for LLM system prompt injection.

### Selective Recall

<ParamField body="message" type="string" required>
  The user's message to determine relevant fields.
</ParamField>

<ParamField body="session_id" type="string" required>
  The session identifier.
</ParamField>

```bash theme={null}
POST /api/schemas/recall
```

```json theme={null}
{
  "message": "What food do I like?",
  "session_id": "alice"
}
```

Runs the CM agent in QA mode to recall only fields relevant to the message. Returns `recalled`, `is_selective`, and `schema_id`.

### Inspect All Schemas

```bash theme={null}
GET /api/schemas/inspect-all
GET /api/schemas/inspect-all?schema_id=default&show_values=true&max_depth=3
```

Returns a token-efficient overview of all schemas.

### Create Schema Domain

```bash theme={null}
POST /api/schemas
```

### Delete Schema Domain

```bash theme={null}
DELETE /api/schemas/{name}
DELETE /api/schemas/{name}?schema_id=default
```

### Delete All Schema Domains

```bash theme={null}
DELETE /api/schemas
DELETE /api/schemas?schema_id=default
```

### Create from Template

<ParamField body="template_name" type="string" required>
  The template name to use.
</ParamField>

<ParamField body="session_id" type="string" required>
  The session identifier.
</ParamField>

```bash theme={null}
POST /api/schemas/from-template
```

```json theme={null}
{
  "template_name": "general",
  "session_id": "alice"
}
```

Copies the template as a new schema file (`{name}_{YYYYMMDD}_{HHmmss}.json`) and switches the session to it.

### Create Schema File

<ParamField body="session_id" type="string" required>
  The session identifier.
</ParamField>

<ParamField body="schema_id" type="string">
  Custom schema ID. Auto-generated if empty.
</ParamField>

<ParamField body="template" type="string">
  Optional template name to populate the new schema.
</ParamField>

```bash theme={null}
POST /api/schemas/create-file
```

```json theme={null}
{
  "session_id": "alice",
  "schema_id": "my_schema",
  "template": "general"
}
```

Creates a new named schema file and switches the session to it. Returns 409 if the schema already exists.

### New Schema (Backup + Reset)

<ParamField body="session_id" type="string" required>
  The session identifier.
</ParamField>

```bash theme={null}
POST /api/schemas/new
```

```json theme={null}
{
  "session_id": "alice"
}
```

Returns `backup_id` and `schema_id`.

### Switch Schema

<ParamField body="session_id" type="string" required>
  The session identifier.
</ParamField>

<ParamField body="target_schema_id" type="string" required>
  The schema ID to switch to.
</ParamField>

```bash theme={null}
POST /api/schemas/switch
```

```json theme={null}
{
  "session_id": "alice",
  "target_schema_id": "default_20260312_143000"
}
```

### Restore Schema

<ParamField body="backup_id" type="string" required>
  The backup identifier to restore.
</ParamField>

```bash theme={null}
POST /api/schemas/restore
```

```json theme={null}
{
  "backup_id": "default_20260312_143000"
}
```

### List Saved Schemas

```bash theme={null}
GET /api/schemas/saved
```

### List Backups

```bash theme={null}
GET /api/schemas/backups
GET /api/schemas/backups?schema_id=default
```

## Templates

### List Templates

```bash theme={null}
GET /api/templates
```

Returns all available templates with info (name, description, source, domain count).

### List Templates (Grouped)

```bash theme={null}
GET /api/templates/grouped
```

Returns templates grouped by source: `builtin`, `user`, `custom`.

### Get Template Details

```bash theme={null}
GET /api/templates/{name}
```

Returns the full template data (same format as schema JSON files).

### Save Custom Template

<ParamField body="template" type="object" required>
  Full template JSON with `_meta.name` field.
</ParamField>

```bash theme={null}
POST /api/templates/custom
```

```json theme={null}
{
  "_meta": {
    "name": "my_template",
    "description": "My custom template"
  },
  "my_domain": {
    "data": {
      "meta": {
        "domain": {"value": "my_domain", "description": "Schema domain"}
      },
      "field1": {"value": "", "description": "First field"}
    },
    "_mutable": true
  }
}
```

Returns `{status, path, name}`.

### Delete Custom Template

```bash theme={null}
DELETE /api/templates/custom/{name}
```

Only custom templates can be deleted. Built-in and user templates are protected.

## Sessions

### List Sessions

```bash theme={null}
GET /api/sessions
```

### Create Session

<ParamField query="session_id" type="string" required>
  The session identifier.
</ParamField>

<ParamField query="schema_id" type="string">
  The schema ID to bind to this session. Defaults to `"default"`.
</ParamField>

```bash theme={null}
POST /api/sessions?session_id=bob&schema_id=default
```

### Delete Session

```bash theme={null}
DELETE /api/sessions/{id}
```

### Clear Session

```bash theme={null}
POST /api/sessions/{id}/clear
```

Clears the session's chat history while preserving schema data.

### Get Session History

```bash theme={null}
GET /api/sessions/{id}/history
```

### Get Session Schema ID

```bash theme={null}
GET /api/sessions/{id}/schema-id
```

### Set Session Schema ID

<ParamField body="schema_id" type="string" required>
  The schema ID to bind to this session.
</ParamField>

```bash theme={null}
PUT /api/sessions/{id}/schema-id
```

```json theme={null}
{
  "schema_id": "default"
}
```