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

> REST API server powered by FastAPI for programmatic integration.

Start the REST API server:

```bash theme={null}
# Foreground mode (default)
loom serve
loom serve --host 0.0.0.0 --port 8666

# Background daemon mode (port from config or via flag)
loom serve start
loom serve --port 9000 start

# Daemon + auto-start on boot
loom serve start --autostart
```

The server also hosts the [Web UI](/interfaces/web-ui) at the root URL.

<Tip>
  For production deployments, use `loom serve start --autostart` to run as a background daemon with boot auto-start. See [Service management](/interfaces/service-management) for details.
</Tip>

## Endpoints Overview

### Core

| Method | Path                           | Description                                      |
| ------ | ------------------------------ | ------------------------------------------------ |
| `POST` | `/api/build`                   | Process text into memory                         |
| `POST` | `/api/chat`                    | Chat with memory (returns `schema_updated` flag) |
| `POST` | `/api/listen`                  | Listen mode: periodic build + every-turn recall  |
| `POST` | `/api/update-schema-from-chat` | Manually update schema from recent chat rounds   |

### Configuration

| Method | Path                                 | Description                              |
| ------ | ------------------------------------ | ---------------------------------------- |
| `GET`  | `/api/config/build-every-n-turns`    | Get current auto-update setting          |
| `PUT`  | `/api/config/build-every-n-turns`    | Change auto-update setting at runtime    |
| `GET`  | `/api/config/chatbot-context-rounds` | Get chatbot context window size          |
| `PUT`  | `/api/config/chatbot-context-rounds` | Change chatbot context window at runtime |

### Schemas

| Method   | Path                                 | Description                                               |
| -------- | ------------------------------------ | --------------------------------------------------------- |
| `GET`    | `/api/schemas`                       | List schema domains                                       |
| `GET`    | `/api/schemas/{name}`                | Get schema details                                        |
| `GET`    | `/api/schemas/file-data/{schema_id}` | Get full domain data from schema file                     |
| `GET`    | `/api/schemas/recall-all`            | Get all schema data as formatted text (for LLM injection) |
| `POST`   | `/api/schemas/recall`                | Selectively recall schema data relevant to a message      |
| `GET`    | `/api/schemas/inspect-all`           | Token-efficient schema overview                           |
| `POST`   | `/api/schemas`                       | Create a new schema domain                                |
| `DELETE` | `/api/schemas/{name}`                | Delete a schema domain                                    |
| `DELETE` | `/api/schemas`                       | Delete all schema domains                                 |
| `POST`   | `/api/schemas/from-template`         | Copy template as a schema file and switch session to it   |
| `POST`   | `/api/schemas/create-file`           | Create a named schema file (with optional template)       |
| `POST`   | `/api/schemas/new`                   | Backup current schema and start fresh                     |
| `POST`   | `/api/schemas/switch`                | Switch session to a different schema                      |
| `POST`   | `/api/schemas/restore`               | Restore a schema from backup                              |
| `GET`    | `/api/schemas/saved`                 | List all standalone schema files                          |
| `GET`    | `/api/schemas/backups`               | List schema backups                                       |

### Templates

| Method   | Path                           | Description                                            |
| -------- | ------------------------------ | ------------------------------------------------------ |
| `GET`    | `/api/templates`               | List available templates with info                     |
| `GET`    | `/api/templates/grouped`       | List templates grouped by source (builtin/user/custom) |
| `GET`    | `/api/templates/{name}`        | Get full template data                                 |
| `POST`   | `/api/templates/custom`        | Save a custom template                                 |
| `DELETE` | `/api/templates/custom/{name}` | Delete a custom template                               |

### Sessions

| Method   | Path                           | Description                                |
| -------- | ------------------------------ | ------------------------------------------ |
| `GET`    | `/api/sessions`                | List sessions (includes `schema_id`)       |
| `POST`   | `/api/sessions`                | Create session (with optional `schema_id`) |
| `DELETE` | `/api/sessions/{id}`           | Delete a session                           |
| `POST`   | `/api/sessions/{id}/clear`     | Clear session history (preserve schemas)   |
| `GET`    | `/api/sessions/{id}/history`   | Get session chat history                   |
| `GET`    | `/api/sessions/{id}/schema-id` | Get session's bound schema ID              |
| `PUT`    | `/api/sessions/{id}/schema-id` | Bind session to a different schema         |

## Usage Examples

### Build Memory

```bash theme={null}
curl -X POST http://localhost:8666/api/build \
  -H "Content-Type: application/json" \
  -d '{"text": "I am Alice, I love hiking.", "session_id": "alice"}'
```

### Chat

```bash theme={null}
curl -X POST http://localhost:8666/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What are my hobbies?", "session_id": "alice"}'
```

### Listen (Periodic Build + Every-Turn Recall)

```bash theme={null}
curl -X POST http://localhost:8666/api/listen \
  -H "Content-Type: application/json" \
  -d '{"message": "I just started learning piano.", "session_id": "alice"}'
```

### Update Schema from Chat

```bash theme={null}
curl -X POST http://localhost:8666/api/update-schema-from-chat \
  -H "Content-Type: application/json" \
  -d '{"session_id": "alice", "rounds": 5}'
```

### Runtime Config

```bash theme={null}
# Get auto-update setting
curl http://localhost:8666/api/config/build-every-n-turns

# Set auto-update to every 3 rounds
curl -X PUT http://localhost:8666/api/config/build-every-n-turns \
  -H "Content-Type: application/json" \
  -d '{"build_every_n_turns": 3}'
```

### Schema Lifecycle

```bash theme={null}
# Backup + reset
curl -X POST http://localhost:8666/api/schemas/new \
  -H "Content-Type: application/json" \
  -d '{"session_id": "alice"}'

# List saved schemas and backups
curl http://localhost:8666/api/schemas/saved
curl http://localhost:8666/api/schemas/backups

# Switch session to a backup
curl -X POST http://localhost:8666/api/schemas/switch \
  -H "Content-Type: application/json" \
  -d '{"session_id": "alice", "target_schema_id": "default_20260312_143000"}'

# Restore a backup
curl -X POST http://localhost:8666/api/schemas/restore \
  -H "Content-Type: application/json" \
  -d '{"backup_id": "default_20260312_143000"}'
```

### Templates

```bash theme={null}
# List all templates
curl http://localhost:8666/api/templates

# List templates grouped by source
curl http://localhost:8666/api/templates/grouped

# Get a specific template
curl http://localhost:8666/api/templates/general

# Save a custom template
curl -X POST http://localhost:8666/api/templates/custom \
  -H "Content-Type: application/json" \
  -d @my_template.json

# Delete a custom template
curl -X DELETE http://localhost:8666/api/templates/custom/my_template
```

### Sessions

```bash theme={null}
# Create a session with a specific schema
curl -X POST "http://localhost:8666/api/sessions?session_id=bob&schema_id=default"

# Get session history
curl http://localhost:8666/api/sessions/alice/history

# Check / change session schema
curl http://localhost:8666/api/sessions/alice/schema-id
curl -X PUT http://localhost:8666/api/sessions/alice/schema-id \
  -H "Content-Type: application/json" \
  -d '{"schema_id": "default"}'
```