Skip to main content
The CogOS REST API is served by FastAPI. Start the server with: 
cogos serve --host 0.0.0.0 --port 8000
Base URL: http://localhost:8000

​
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 buildEveryNTurns 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 Schema Update Rounds

GET /api/config/schema-update-rounds

​
Set Schema Update Rounds

PUT /api/config/schema-update-rounds

{
  "schema_update_rounds": 5
}

​
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"
}