Skip to main content
Start the REST API server: 
cogos serve
# or
cogos serve --host 0.0.0.0 --port 8000
The server also hosts the Web UI at the root URL.

​
Endpoints Overview

​
Core

MethodPathDescription
POST/api/buildProcess text into memory
POST/api/chatChat with memory (returns schema_updated flag)
POST/api/listenListen mode: periodic build + every-turn recall
POST/api/update-schema-from-chatManually update schema from recent chat rounds

​
Configuration

MethodPathDescription
GET/api/config/schema-update-roundsGet current auto-update setting
PUT/api/config/schema-update-roundsChange auto-update setting at runtime
GET/api/config/chatbot-context-roundsGet chatbot context window size
PUT/api/config/chatbot-context-roundsChange chatbot context window at runtime

​
Schemas

MethodPathDescription
GET/api/schemasList 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-allGet all schema data as formatted text (for LLM injection)
POST/api/schemas/recallSelectively recall schema data relevant to a message
GET/api/schemas/inspect-allToken-efficient schema overview
POST/api/schemasCreate a new schema domain
DELETE/api/schemas/{name}Delete a schema domain
DELETE/api/schemasDelete all schema domains
POST/api/schemas/from-templateCopy template as a schema file and switch session to it
POST/api/schemas/create-fileCreate a named schema file (with optional template)
POST/api/schemas/newBackup current schema and start fresh
POST/api/schemas/switchSwitch session to a different schema
POST/api/schemas/restoreRestore a schema from backup
GET/api/schemas/savedList all standalone schema files
GET/api/schemas/backupsList schema backups

​
Templates

MethodPathDescription
GET/api/templatesList available templates with info
GET/api/templates/groupedList templates grouped by source (builtin/user/custom)
GET/api/templates/{name}Get full template data
POST/api/templates/customSave a custom template
DELETE/api/templates/custom/{name}Delete a custom template

​
Sessions

MethodPathDescription
GET/api/sessionsList sessions (includes schema_id)
POST/api/sessionsCreate session (with optional schema_id)
DELETE/api/sessions/{id}Delete a session
POST/api/sessions/{id}/clearClear session history (preserve schemas)
GET/api/sessions/{id}/historyGet session chat history
GET/api/sessions/{id}/schema-idGet session’s bound schema ID
PUT/api/sessions/{id}/schema-idBind session to a different schema

​
Usage Examples

​
Build Memory

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

​
Chat

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

​
Listen (Periodic Build + Every-Turn Recall)

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

​
Update Schema from Chat

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

​
Runtime Config

# Get auto-update setting
curl http://localhost:8000/api/config/schema-update-rounds

# Set auto-update to every 5 rounds
curl -X PUT http://localhost:8000/api/config/schema-update-rounds \
  -H "Content-Type: application/json" \
  -d '{"schema_update_rounds": 5}'

​
Schema Lifecycle

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

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

# Switch session to a backup
curl -X POST http://localhost:8000/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:8000/api/schemas/restore \
  -H "Content-Type: application/json" \
  -d '{"backup_id": "default_20260312_143000"}'

​
Templates

# List all templates
curl http://localhost:8000/api/templates

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

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

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

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

​
Sessions

# Create a session with a specific schema
curl -X POST "http://localhost:8000/api/sessions?session_id=bob&schema_id=default"

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

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