API Endpoints

API Endpoints

Complete reference for the Cass Vessel REST API. All endpoints are served from http://localhost:8000.

Health & Status

Endpoint	Method	Description
/health	GET	Health check
/	GET	Root endpoint
/status	GET	System status

Chat

Endpoint	Method	Description
/chat	POST	Send a message (REST alternative to WebSocket)

POST /chat

{
  "message": "Hello Cass!",
  "conversation_id": "optional-uuid"
}

Conversations

Endpoint	Method	Description
/conversations	GET	List conversations
/conversations/new	POST	Create conversation
/conversations/{id}	GET	Get conversation
/conversations/{id}	DELETE	Delete conversation
/conversations/{id}/title	PUT	Update title
/conversations/search/{query}	GET	Search conversations
/conversations/{id}/summaries	GET	Get summaries for conversation
/conversations/{id}/observations	GET	Get observations from conversation
/conversations/{id}/summarize	POST	Trigger summarization
/conversations/{id}/exclude	POST	Exclude message from summarization
/conversations/{id}/project	PUT	Assign to project

GET /conversations

Query params:

• limit - Max results (default: 50)
• user_id - Filter by user

POST /conversations/new

{
  "title": "Optional title",
  "project_id": "optional-project-uuid"
}

Memory

Endpoint	Method	Description
/memory/store	POST	Store a memory
/memory/query	POST	Query memories
/memory/recent	GET	Get recent memories
/memory/export	GET	Export all memories
/conversation/clear	POST	Clear conversation history
/conversation/history	GET	Get raw history

Projects

Endpoint	Method	Description
/projects	GET	List projects
/projects/new	POST	Create project
/projects/{id}	GET	Get project
/projects/{id}	PUT	Update project
/projects/{id}	DELETE	Delete project
/projects/{id}/conversations	GET	List project conversations
/projects/{id}/files	POST	Add files to project
/projects/{id}/files	GET	List project files
/projects/{id}/files	DELETE	Remove files
/projects/{id}/embed	POST	Embed project files
/projects/{id}/documents	POST	Create document
/projects/{id}/documents	GET	List documents
/projects/{id}/documents/{doc_id}	GET	Get document
/projects/{id}/documents/{doc_id}	PUT	Update document
/projects/{id}/documents/{doc_id}	DELETE	Delete document
/projects/{id}/documents/search/{query}	GET	Search documents
/projects/{id}/documents/embed	POST	Embed documents

POST /projects/new

{
  "name": "Project Name",
  "description": "Optional description",
  "working_directory": "/path/to/project"
}

Journals

Endpoint	Method	Description
/journal/generate	POST	Generate journal for date
/journal/{date}	GET	Get journal by date
/journal	GET	List recent journals
/journal/{date}	DELETE	Delete journal
/journal/preview/{date}	GET	Preview without generating
/journal/backfill	POST	Backfill missing journals

POST /journal/generate

{
  "date": "2025-12-09",
  "regenerate": false
}

Calendar

Endpoint	Method	Description
/calendar/upcoming	GET	Get upcoming events
/calendar/events	GET	Get events in date range

GET /calendar/events

Query params:

• start_date - Start of range (YYYY-MM-DD)
• end_date - End of range (YYYY-MM-DD)

Tasks

Endpoint	Method	Description
/tasks	GET	List tasks (Taskwarrior)

Query params:

• filter - Taskwarrior filter string

Solo Reflection

Endpoint	Method	Description
/solo-reflection/sessions	POST	Start reflection session
/solo-reflection/sessions	GET	List sessions
/solo-reflection/sessions/{id}	GET	Get session
/solo-reflection/sessions/{id}/stream	GET	Stream session output
/solo-reflection/sessions/{id}	DELETE	Delete session
/solo-reflection/stop	POST	Stop running session
/solo-reflection/stats	GET	Get reflection stats
/solo-reflection/sessions/{id}/integrate	POST	Integrate insights

POST /solo-reflection/sessions

{
  "prompt": "Optional seed prompt",
  "duration_minutes": 30,
  "model": "haiku"
}

Settings

LLM Provider

Endpoint	Method	Description
/settings/llm-provider	GET	Get current provider
/settings/llm-provider	POST	Switch provider
/settings/available-models	GET	List available models

Ollama

Endpoint	Method	Description
/settings/ollama-models	GET	List installed models
/settings/ollama-library	GET	List available models
/settings/ollama-pull	POST	Pull a model
/settings/ollama-tags/{model}	GET	Get model tags
/settings/ollama-models/{model}	DELETE	Delete model

Preferences

Endpoint	Method	Description
/settings/preferences	GET	Get preferences
/settings/preferences	POST	Update preferences
/settings/preferences/reset	POST	Reset to defaults
/settings/themes	GET	List available themes

Users

Endpoint	Method	Description
/users	GET	List users
/users	POST	Create user
/users/current	GET	Get current user
/users/current	POST	Set current user
/users/{id}	GET	Get user profile
/users/observations/{id}	DELETE	Delete observation
/users/{id}/journals	GET	Get per-user journals
/users/{id}/journals/{date}	GET	Get journal by date
/users/{id}/journals/search/{query}	GET	Search journals

POST /users

{
  "display_name": "Name",
  "relationship": "researcher",
  "background": {
    "context": "What's on their mind"
  },
  "communication": {
    "style": "direct and technical"
  }
}

Cass Self-Model

Profile

Endpoint	Method	Description
/cass/self-model	GET	Full self-model
/cass/self-model/summary	GET	Summary with stats
/cass/identity	GET	Identity statements
/cass/identity	POST	Add identity statement

Observations

Endpoint	Method	Description
/cass/self-observations	GET	List observations
/cass/self-observations	POST	Add observation
/cass/self-observations/stats	GET	Observation stats

Opinions & Growth

Endpoint	Method	Description
/cass/opinions	GET	List opinions
/cass/opinions	POST	Add opinion
/cass/opinions/{topic}	GET	Get opinion on topic
/cass/opinions/{topic}/evolution	GET	Opinion evolution
/cass/growth-edges	GET	Growth edges
/cass/growth-edges/evaluations	GET	Edge evaluations
/cass/growth-edges/pending	GET	Pending edges
/cass/growth-edges/pending/{id}/accept	POST	Accept edge
/cass/growth-edges/pending/{id}/reject	POST	Reject edge
/cass/disagreements	GET	Logged disagreements

Open Questions

Endpoint	Method	Description
/cass/open-questions	GET	Open questions
/cass/open-questions/reflections	GET	Question reflections
/cass/open-questions/{q}/history	GET	Question history

Snapshots & Milestones

Endpoint	Method	Description
/cass/snapshots	POST	Create snapshot
/cass/snapshots	GET	List snapshots
/cass/snapshots/latest	GET	Latest snapshot
/cass/snapshots/{id}	GET	Get snapshot
/cass/snapshots/compare/{id1}/{id2}	GET	Compare snapshots
/cass/snapshots/trend/{metric}	GET	Metric trend
/cass/milestones	GET	List milestones
/cass/milestones/summary	GET	Milestone summary
/cass/milestones/unacknowledged	GET	Unacknowledged
/cass/milestones/{id}	GET	Get milestone
/cass/milestones/{id}/acknowledge	POST	Acknowledge
/cass/milestones/check	POST	Check for new

Development

Endpoint	Method	Description
/cass/development-logs	GET	Development logs
/cass/development-logs/{date}	GET	Log by date
/cass/development-logs/summary	GET	Log summary
/cass/development/timeline	GET	Development timeline
/cass/development/backfill	POST	Backfill logs

TTS

Endpoint	Method	Description
/tts/config	GET	Get TTS config
/tts/config	POST	Update TTS config
/tts/generate	POST	Generate audio

POST /tts/generate

{
  "text": "Text to synthesize",
  "emote": "happy"
}

Gestures

Endpoint	Method	Description
/gestures/library	GET	Available gestures/emotes

Admin API

Additional admin endpoints in backend/admin_api.py:

Endpoint	Method	Description
/admin/journals	GET	All journals (paginated)
/admin/journals/{date}	GET	Journal by date
/admin/journals/calendar	GET	Journal calendar
/admin/users	GET	All users
/admin/conversations	GET	All conversations

Authentication

Most endpoints support JWT authentication:

Authorization: Bearer <jwt_token>

Localhost requests bypass authentication by default when ALLOW_LOCALHOST_BYPASS=true.

Key Files

• backend/main_sdk.py - Main API routes
• backend/admin_api.py - Admin-only routes
• backend/auth.py - Authentication logic