API Reference

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

loom serve --host 0.0.0.0 --port 8666

Base URL: http://localhost:8666

Core

Build Memory

text

string

required

The text to process into memory.

session_id

string

required

The session identifier.

POST /api/build

{
  "text": "I am Alice, I love hiking.",
  "session_id": "alice"
}

Chat

message

string

required

The user’s message.

session_id

string

required

The session identifier.

POST /api/chat

{
  "message": "What are my hobbies?",
  "session_id": "alice"
}

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

Listen

message

string

required

The user’s message.

session_id

string

required

The session identifier.

POST /api/listen

{
  "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

session_id

string

required

The session identifier.

rounds

integer

Number of recent chat rounds to process.

POST /api/update-schema-from-chat

{
  "session_id": "alice",
  "rounds": 5
}

Configuration

Get Build Every N Turns

GET /api/config/build-every-n-turns

Set Build Every N Turns

PUT /api/config/build-every-n-turns

{
  "build_every_n_turns": 3
}

Get Chatbot Context Rounds

GET /api/config/chatbot-context-rounds

Set Chatbot Context Rounds

PUT /api/config/chatbot-context-rounds

{
  "context_rounds": 10
}

Schemas

List Schema Domains

GET /api/schemas

Get Schema Details

GET /api/schemas/{name}

Get Schema File Data

GET /api/schemas/file-data/{schema_id}

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

Recall All Schemas

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

message

string

required

The user’s message to determine relevant fields.

session_id

string

required

The session identifier.

POST /api/schemas/recall

{
  "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

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

POST /api/schemas

Delete Schema Domain

DELETE /api/schemas/{name}
DELETE /api/schemas/{name}?schema_id=default

Delete All Schema Domains

DELETE /api/schemas
DELETE /api/schemas?schema_id=default

Create from Template

template_name

string

required

The template name to use.

session_id

string

required

The session identifier.

POST /api/schemas/from-template

{
  "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

session_id

string

required

The session identifier.

schema_id

string

Custom schema ID. Auto-generated if empty.

template

string

Optional template name to populate the new schema.

POST /api/schemas/create-file

{
  "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)

session_id

string

required

The session identifier.

POST /api/schemas/new

{
  "session_id": "alice"
}

Returns backup_id and schema_id.

Switch Schema

session_id

string

required

The session identifier.

target_schema_id

string

required

The schema ID to switch to.

POST /api/schemas/switch

{
  "session_id": "alice",
  "target_schema_id": "default_20260312_143000"
}

Restore Schema

backup_id

string

required

The backup identifier to restore.

POST /api/schemas/restore

{
  "backup_id": "default_20260312_143000"
}

List Saved Schemas

GET /api/schemas/saved

List Backups

GET /api/schemas/backups
GET /api/schemas/backups?schema_id=default

Templates

List Templates

GET /api/templates

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

List Templates (Grouped)

GET /api/templates/grouped

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

Get Template Details

GET /api/templates/{name}

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

Save Custom Template

template

object

required

Full template JSON with _meta.name field.

POST /api/templates/custom

{
  "_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

DELETE /api/templates/custom/{name}

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

Sessions

List Sessions

GET /api/sessions

Create Session

session_id

string

required

The session identifier.

schema_id

string

The schema ID to bind to this session. Defaults to "default".

POST /api/sessions?session_id=bob&schema_id=default

Delete Session

DELETE /api/sessions/{id}

Clear Session

POST /api/sessions/{id}/clear

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

Get Session History

GET /api/sessions/{id}/history

Get Session Schema ID

GET /api/sessions/{id}/schema-id

Set Session Schema ID

schema_id

string

required

The schema ID to bind to this session.

PUT /api/sessions/{id}/schema-id

{
  "schema_id": "default"
}

​Core

​Build Memory

​Chat

​Listen

​Update Schema from Chat

​Configuration

​Get Build Every N Turns

​Set Build Every N Turns

​Get Chatbot Context Rounds

​Set Chatbot Context Rounds

​Schemas

​List Schema Domains

​Get Schema Details

​Get Schema File Data

​Recall All Schemas

​Selective Recall

​Inspect All Schemas

​Create Schema Domain

​Delete Schema Domain

​Delete All Schema Domains

​Create from Template

​Create Schema File

​New Schema (Backup + Reset)

​Switch Schema

​Restore Schema

​List Saved Schemas

​List Backups

​Templates

​List Templates

​List Templates (Grouped)

​Get Template Details

​Save Custom Template

​Delete Custom Template

​Sessions

​List Sessions

​Create Session

​Delete Session

​Clear Session

​Get Session History

​Get Session Schema ID

​Set Session Schema ID

Core

Build Memory

Chat

Listen

Update Schema from Chat

Configuration

Get Build Every N Turns

Set Build Every N Turns

Get Chatbot Context Rounds

Set Chatbot Context Rounds

Schemas

List Schema Domains

Get Schema Details

Get Schema File Data

Recall All Schemas

Selective Recall

Inspect All Schemas

Create Schema Domain

Delete Schema Domain

Delete All Schema Domains

Create from Template

Create Schema File

New Schema (Backup + Reset)

Switch Schema

Restore Schema

List Saved Schemas

List Backups

Templates

List Templates

List Templates (Grouped)

Get Template Details

Save Custom Template

Delete Custom Template

Sessions

List Sessions

Create Session

Delete Session

Clear Session

Get Session History

Get Session Schema ID

Set Session Schema ID