Morphee API Reference

Complete API documentation for morphee-server (Rust/axum).

Last Updated: February 28, 2026

---

Base URL

Development: http://localhost:3000 Production: https://yourdomain.com/v1

The morphee-server is a Rust/axum HTTP server wrapping morphee-core. Base URL is configurable via MORPHEE_HOST/MORPHEE_PORT.

Note: The Python backend (FastAPI, port 8000) was retired in V2.0. Legacy Python API docs are archived at docs/archive/api-python-legacy.md.

---

Authentication

Status: Implemented (Supabase Auth with GoTrue)

Protected endpoints require JWT authentication in the Authorization header:

Authorization: Bearer <jwt_token>

Get your access token by signing in or signing up through the /v1/auth/signup or /v1/auth/signin endpoints.

Authentication Flow:

1. Sign up → /v1/auth/signup → Receive access_token and refresh_token
2. Sign in → /v1/auth/signin → Receive access_token and refresh_token
3. Use access_token in Authorization: Bearer <token> header for protected endpoints
4. Refresh token when expired → /v1/auth/refresh

The AuthIdentity middleware verifies tokens via CompositeAuth (SupabaseAuth + MorpheeAuth, routing by JWT iss claim).

---

Common Response Formats

Success Response

{
  "id": "uuid",
  "status": "success",
  "data": { ... }
}

Error Response

{
  "detail": "Error message",
  "status_code": 400,
  "error_type": "ValidationError"
}

HTTP Status Codes

• 200 OK: Successful GET request
• 201 Created: Successful POST request
• 204 No Content: Successful DELETE request
• 400 Bad Request: Invalid request data
• 404 Not Found: Resource not found
• 422 Unprocessable Entity: Validation error
• 500 Internal Server Error: Server error

---

Health

GET /health

Health check endpoint (no auth required).

Response: 200 OK

{ "status": "ok" }

---

Auth & Knowledge Signing

POST /v1/auth/verify

Verify a JWT token and return identity.

Request:

{ "token": "eyJ..." }

Response: 200 OK

{ "id": "user-uuid", "provider": "Supabase", "roles": ["user"], "group_id": "group-uuid" }

POST /v1/auth/token

Issue a new JWT token (for child/service accounts).

GET /v1/auth/signers

List trusted signers for the authenticated user's group.

POST /v1/knowledge/sign

Sign compiled knowledge (WASM binary) with Ed25519.

POST /v1/knowledge/verify

Verify a knowledge signature and trust chain.

---

Chat (SSE Streaming)

POST /v1/chat

Send a message and receive SSE-streamed response. Requires auth.

Request:

{
  "content": "What is 2+2?",
  "conversation_id": "optional-uuid",
  "space_id": "optional-uuid"
}

Response: SSE stream with events:

data: {"event":"conversation_id","data":"conv-uuid"}

data: {"event":"text_delta","data":"The answer"}

data: {"event":"text_delta","data":" is 4."}

data: {"event":"done","data":null}

Event types: conversation_id, text_delta, tool_use, tool_result, approval_request, done, error

POST /v1/chat/component-event

Dispatch a component event (stub — logs and returns acknowledgment). Requires auth.

Request:

{
  "source": { "component_id": "c1", "component_type": "form", "conversation_id": "conv-uuid" },
  "event_type": "submit",
  "payload": { "name": "Alice" },
  "tier": "ai_turn"
}

Response: 200 OK

{ "status": "received" }

POST /v1/chat/approve/{id}

Approve a pending tool/action (stub). Requires auth.

Response: 200 OK

{ "status": "approved", "approval_id": "uuid" }

---

Conversations

GET /v1/conversations

List conversations (group-scoped). Supports pagination via ?limit=50&offset=0.

Response: 200 OK — Array of Conversation objects.

POST /v1/conversations

Create a new conversation.

Request:

{
  "title": "Math Help",
  "space_id": "optional-uuid"
}

Response: 201 Created — Conversation object.

GET /v1/conversations/{id}

Get a specific conversation.

PATCH /v1/conversations/{id}

Update a conversation (title, archived status).

Request:

{
  "title": "Updated Title",
  "archived": false
}

DELETE /v1/conversations/{id}

Delete a conversation and all its messages (cascade).

GET /v1/conversations/{id}/messages

List messages for a conversation.

Response: 200 OK — Array of PersistedMessage objects with role, content, tool_calls, tool_results, metadata, pinned, reactions, edited_at.

POST /v1/conversations/{id}/messages/{msg_id}/pin

Pin a message. Requires auth.

Response: 200 OK

{ "status": "pinned" }

DELETE /v1/conversations/{id}/messages/{msg_id}/pin

Unpin a message. Requires auth.

Response: 200 OK

{ "status": "unpinned" }

GET /v1/conversations/{id}/messages/pinned

List pinned messages for a conversation. Requires auth.

Response: 200 OK — Array of PersistedMessage objects where pinned=true.

POST /v1/conversations/{id}/messages/{msg_id}/react

Add a reaction to a message. Requires auth.

Request:

{ "emoji": "👍" }

Response: 200 OK

{ "status": "reaction_added" }

DELETE /v1/conversations/{id}/messages/{msg_id}/react

Remove a reaction from a message. Requires auth.

Request:

{ "emoji": "👍" }

Response: 200 OK

{ "status": "reaction_removed" }

PATCH /v1/conversations/{id}/messages/{msg_id}

Update message content. Sets edited_at timestamp. Requires auth.

Request:

{ "content": "Updated message text" }

Response: 200 OK

{ "status": "updated" }

POST /v1/conversations/{id}/regenerate

Regenerate the last AI response (stub). Requires auth.

Response: 200 OK

{ "status": "not_implemented" }

POST /v1/conversations/sync-local

Sync a local conversation to the server. Creates conversation if needed, inserts user + assistant messages. Requires auth.

Request:

{
  "conversation_id": "local-uuid",
  "title": "My Conversation",
  "user_message": "Hello",
  "assistant_message": "Hi there!"
}

Response: 200 OK

{ "status": "synced", "conversation_id": "uuid" }

---

Memory

POST /v1/memory

Store a memory (embed text + insert into VectorDB).

Request:

{
  "content": "User prefers dark mode",
  "metadata": { "type": "preference" }
}

Response: 201 Created

{ "id": "mem-uuid", "dimensions": 384 }

GET /v1/memory/search

Search memory by vector similarity.

Query params: ?q=dark+mode&limit=10

Response: 200 OK

{
  "results": [
    { "id": "mem-uuid", "content": "User prefers dark mode", "score": 0.95, "metadata": {} }
  ]
}

DELETE /v1/memory/{id}

Delete a memory from VectorDB.

POST /v1/embed

Embed text and return the vector.

Request:

{ "text": "Hello world" }

Response: 200 OK

{ "embedding": [0.1, 0.2, ...], "dimensions": 384 }

---

Skills

GET /v1/skills

List skills (group-scoped).

Response: 200 OK — Array of PersistedSkill objects.

POST /v1/skills

Create a skill.

Request:

{
  "name": "Unit Converter",
  "description": "Converts between units",
  "definition": { "steps": [...] },
  "space_id": "optional-uuid"
}

Response: 201 Created — PersistedSkill object.

GET /v1/skills/{id}

Get a specific skill.

PUT /v1/skills/{id}

Update a skill (name, description, definition, enabled).

DELETE /v1/skills/{id}

Delete a skill.

---

Search

GET /v1/search

Unified search across conversations, memory, and skills.

Query params: ?q=dark+mode&types=conversations,memory,skills&limit=20

Response: 200 OK

{
  "results": [
    { "id": "uuid", "result_type": "memory", "title": "Preference", "content": "User prefers dark mode", "score": 0.95 }
  ]
}

---

WebSocket

GET /v1/ws

WebSocket upgrade endpoint. Auth via query param: ?token=<jwt>.

Protocol: JSON messages for process/signal commands. Server pushes EventBus events.

---

Pipeline

POST /v1/process

Process a query through the Pipeline. Requires auth.

POST /v1/process/stream

Process a query with SSE streaming response.

POST /v1/signal

Send feedback signal (accept/reject/approve) to the Pipeline.

GET /v1/capabilities

List Pipeline capabilities for the authenticated session.

GET /v1/models

List available models.

POST /v1/models/{id}/download

Download a model.

DELETE /v1/models/{id}

Delete a model.

---

Auth CRUD

POST /v1/auth/signup

Sign up via GoTrue (email/password). Creates morphee user record.

Request:

{ "email": "user@example.com", "password": "secret123" }

Response: 201 Created — AuthTokenResponse with access_token, refresh_token, expires_in, user.

POST /v1/auth/signin

Sign in via GoTrue. Returns JWT + httpOnly refresh cookie.

POST /v1/auth/refresh

Refresh access token. Reads morphee_refresh_token cookie or JSON body.

POST /v1/auth/signout

Invalidate session. Clears refresh cookie. Requires auth.

GET /v1/auth/me

Get current user info. Falls back to JWT identity if DB unavailable. Requires auth.

GET /v1/auth/profile | PATCH /v1/auth/profile

Get or update user profile (display_name, avatar_url, locale). Requires auth.

POST /v1/auth/change-password

Change password via GoTrue. Requires auth.

POST /v1/auth/delete-account

GDPR Art. 17 cascade delete (user + all group data). Requires auth.

GET /v1/auth/export

GDPR Art. 20 data export (JSON). Requires auth.

GET /v1/auth/consents | POST /v1/auth/consents | DELETE /v1/auth/consents

GDPR consent CRUD. Requires auth (except GET /v1/auth/consents/required).

GET /v1/auth/consents/required

List required consent types. No auth required.

POST /v1/auth/step-up/challenge | POST /v1/auth/step-up/verify

Step-up authentication. Challenge returns challenge_id (5-min TTL). Verify validates response and issues elevated token (15-min TTL). Requires auth.

---

Groups + Members + Invites

POST /v1/groups

Create a group. Requires auth.

GET /v1/groups/me | PATCH /v1/groups/me | DELETE /v1/groups/me

Get, update, or delete the current user's group. Requires auth.

GET /v1/groups/me/members | PATCH /v1/groups/me/members/{user_id} | DELETE /v1/groups/me/members/{user_id}

Member management. Only owner/parent can modify. Requires auth.

POST /v1/groups/me/invites | POST /v1/groups/me/invites/link | GET /v1/groups/me/invites | DELETE /v1/groups/me/invites/{id}

Invite management. Email invites and shareable links. Only owner/parent can create. Requires auth.

POST /v1/groups/invites/accept | POST /v1/groups/invites/decline

Accept or decline an invite (by invite_id or token). Requires auth.

GET /v1/auth/parent-consent/verify/{token}

Verify parent consent token. No auth required.

POST /v1/auth/parent-consent/resend | GET /v1/auth/parent-consent/status

Resend consent token or check status. Requires auth.

---

Spaces + Tasks + Canvas

POST /v1/spaces | GET /v1/spaces | GET /v1/spaces/stats

Space CRUD with stats (conversation/canvas/task counts per space). Requires auth.

GET /v1/spaces/{id} | PATCH /v1/spaces/{id} | DELETE /v1/spaces/{id}

Space detail operations. Group-scoped. Requires auth.

POST /v1/spaces/morph/register | PATCH /v1/spaces/{id}/morph-path

Register or update a .morph path for a space. Requires auth.

GET /v1/spaces/{id}/sync-status

Query sync repo status for a space (knowledge network). Requires auth.

POST /v1/tasks | GET /v1/tasks

Task CRUD. Requires auth.

GET /v1/tasks/{id} | PATCH /v1/tasks/{id} | DELETE /v1/tasks/{id}

Task detail operations. Requires auth.

POST /v1/tasks/{id}/pause | POST /v1/tasks/{id}/resume | POST /v1/tasks/{id}/cancel

Task state transitions. Validates state machine (pending → running → completed/failed/cancelled, paused as side state). Requires auth.

POST /v1/canvas | GET /v1/canvas

Canvas CRUD. Requires auth.

GET /v1/canvas/{id} | PUT /v1/canvas/{id} | PATCH /v1/canvas/{id} | DELETE /v1/canvas/{id}

Canvas detail operations. JSONB components/positions/sections. Requires auth.

GET /v1/canvas/state | PUT /v1/canvas/state

Legacy default canvas shim. Requires auth.

---

Identity + SSO + OAuth

POST /v1/identity/children | GET /v1/identity/children | DELETE /v1/identity/children/{id}

Child identity CRUD. Requires auth (parent).

POST /v1/identity/auth/child | POST /v1/identity/auth/child/refresh | POST /v1/identity/auth/switch-to-parent

Child authentication. Issues Morphee JWT with aud=morphee_child. Requires auth.

POST /v1/identity/{user_id}/biometric/register | POST /v1/identity/auth/child/biometric | DELETE /v1/identity/{user_id}/biometric/{method}

Biometric auth (face/voice). Requires auth.

GET /v1/identity/methods | POST /v1/identity/methods | DELETE /v1/identity/methods/{id}

Auth method management. Requires auth.

GET /v1/identity/sessions | DELETE /v1/identity/sessions | DELETE /v1/identity/sessions/{id}

Session management. Requires auth.

GET /v1/auth/providers

List available SSO providers. No auth required.

GET /v1/auth/sso/{provider}

Get SSO authorization URL (redirects to provider). No auth required.

POST /v1/auth/sso/callback

SSO callback — exchanges GoTrue authorization code for tokens, find-or-creates user.

GET /v1/oauth/authorize | GET /v1/oauth/callback | DELETE /v1/oauth/disconnect

OAuth connection management (Google Calendar, Gmail, etc.). Requires auth (except callback).

GET /v1/oauth/{provider}/status

Check OAuth connection status for a provider (e.g., google). Returns whether connected and granted scopes. Requires auth.

Response: 200 OK

{ "connected": true, "provider": "google", "scopes": ["calendar.readonly", "gmail.readonly"] }

---

Notifications + Push + ACL + Onboarding

GET /v1/notifications | POST /v1/notifications/{id}/read | POST /v1/notifications/read-all | GET /v1/notifications/unread-count

Notification management. Requires auth.

GET /v1/notifications/preferences | PATCH /v1/notifications/preferences

Notification preferences. Requires auth.

POST /v1/push/register | DELETE /v1/push/unregister

Push token management (APNs/FCM). Requires auth.

GET /v1/acl | POST /v1/acl/grant | POST /v1/acl/revoke | POST /v1/acl/check

ACL management. Requires auth.

GET /v1/acl/preferences | PATCH /v1/acl/preferences

ACL user preferences. Requires auth.

GET /v1/acl/monitoring/requested | GET /v1/acl/monitoring/received | POST /v1/acl/monitoring/request | POST /v1/acl/monitoring/consent

ACL monitoring permissions. Requires auth.

POST /v1/onboarding/quick-setup

Create group + default spaces + child identities in one call. Requires auth.

Request:

{
  "group_name": "Smith Family",
  "display_name": "John",
  "locale": "en",
  "children": [{ "display_name": "Emma", "age": 8 }]
}

POST /v1/onboarding/chat

SSE onboarding chat stream. Requires auth.

---

Interfaces + Extensions

GET /v1/interfaces | GET /v1/interfaces/actions | POST /v1/interfaces/execute

Interface management. List available integrations and execute actions.

GET /v1/interfaces/configs | POST /v1/interfaces/configs | PATCH /v1/interfaces/configs/{id} | DELETE /v1/interfaces/configs/{id}

Interface configuration CRUD (by ID). Requires auth.

GET /v1/interfaces/{name}/config | PUT /v1/interfaces/{name}/config | DELETE /v1/interfaces/{name}/config

Interface configuration by integration type name (e.g., google_calendar, openai). GET retrieves, PUT upserts, DELETE removes. Requires auth.

GET /v1/extensions/catalog | GET /v1/extensions

Extension catalog (all available) and installed extensions.

POST /v1/extensions/upload

Upload WASM extension bytes. Validates magic bytes, computes FNV-1a hash, stores in PostgreSQL. Returns wasm_hash for use with install. If WASM runtime is enabled, also compiles and caches the module. Requires auth.

POST /v1/extensions/install | DELETE /v1/extensions/{id} | POST /v1/extensions/{id}/execute

Extension lifecycle management. Install accepts optional wasm_hash to load pre-uploaded WASM. Execute runs the action via the WASM runtime (returns 503 if runtime disabled). Every execution is recorded in the audit log. Requires auth.

GET /v1/extensions/{id} | POST /v1/extensions/{id}/enable | POST /v1/extensions/{id}/disable

Extension detail and toggle. Requires auth.

GET /v1/extensions/{id}/audit | PUT /v1/extensions/{id}/permissions | PUT /v1/extensions/{id}/limits

Extension security metadata. Requires auth.