API Server - CogOS

Start the REST API server:

# Foreground mode (default)
cogos serve
cogos serve --host 0.0.0.0 --port 8000

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

# Daemon + auto-start on boot
cogos serve start --autostart

The server also hosts the Web UI at the root URL.

For production deployments, use cogos serve start --autostart to run as a background daemon with boot auto-start. See Service management for details.

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/schema-update-rounds`	Get current auto-update setting
`PUT`	`/api/config/schema-update-rounds`	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

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

​Endpoints Overview

​Core

​Configuration

​Schemas

​Templates

​Sessions

​Usage Examples

​Build Memory

​Chat

​Listen (Periodic Build + Every-Turn Recall)

​Update Schema from Chat

​Runtime Config

​Schema Lifecycle

​Templates

​Sessions

Endpoints Overview

Core

Configuration

Schemas

Templates

Sessions

Usage Examples

Build Memory

Chat

Listen (Periodic Build + Every-Turn Recall)

Update Schema from Chat

Runtime Config

Schema Lifecycle

Templates

Sessions