API Reference

All endpoints return ApiEnvelope<T>:

{
  "ok": true,
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "data": { ... },
  "count": 42,
  "error": null,
  "errorCode": null,
  "hint": null
}

Error responses:

{
  "ok": false,
  "requestId": "550e8400-e29b-41d4-a716-446655440001",
  "data": null,
  "error": "Identity not found: 99",
  "errorCode": "NOT_FOUND",
  "hint": "Check identity ID or use identity_list to find valid IDs"
}

Headers

Header	Direction	Description
`Authorization`	Request	`Bearer {jwt}` or `ApiKey {atm_...}`
`X-Correlation-Id`	Both	UUID correlating the request. Auto-generated if not sent.
`X-Identity-Id`	Response	Identity that processed the request (API key auth)

Rate Limiting

Auth endpoints: rate-limited per IP
Signup: 3 per 5 minutes per IP
General endpoints: per-tenant rate limits based on plan

Authentication

Login

POST /api/auth/login

Field	Type	Required	Description
`username`	string	yes	Username
`password`	string	yes	Password

Response: { accessToken, refreshToken, expiresAt, user }

Refresh Token

POST /api/auth/refresh

Field	Type	Required
`refreshToken`	string	yes

Rotates the refresh token. Previous token is invalidated.

API Key Login

POST /api/auth/apikey

Field	Type	Required
`apiKey`	string	yes

Signup

POST /api/auth/signup

Field	Type	Required	Validation
`username`	string	yes	3-50 chars, alphanumeric + hyphens
`email`	string	yes	Must contain @
`password`	string	yes	8+ characters

Bootstrap

POST /api/auth/bootstrap

Only works when no users exist. Creates first admin user and auto-logs in.

Field	Type	Required
`username`	string	yes
`password`	string	yes
`email`	string	yes

Current User

GET /api/auth/me

Auth: Required. Response: UserDto

Device Authentication

POST /api/auth/device          -- Register device (auth required)
GET  /api/auth/devices         -- List devices (auth required)
GET  /api/auth/device/{id}     -- Get device
PUT  /api/auth/device/{id}     -- Update device
DELETE /api/auth/device/{id}   -- Delete device
POST /api/auth/device/challenge -- Request challenge (public)
POST /api/auth/device/login    -- Complete auth with signed challenge (public)

Hydration

Hydrate

GET /api/hydrate

Auth: Required. Permission: HydrationView.

Parameter	Type	Default	Description
`aiName`	string	null	AI identity name
`projectId`	long	null	Scope to project
`preset`	string	`lean`	`lean`, `interactive`, `all`, `agent-minimal`, `agent`
`generateSystemPrompt`	bool	true	Include system prompt
`identityMemoryLimit`	int	20	Max identity memories
`pinnedMemoryLimit`	int	20	Max pinned memories
`recentMemoryLimit`	int	10	Max recent memories
`contentMaxLength`	int	500	Content truncation length
`factLimit`	int	30	Max facts
`minFactImportance`	int	0	Min fact importance
`pendingReplyLimit`	int	5	Max pending replies
`excludeSources`	string	null	Comma-separated sources to exclude

Response: HydrationContext -- structured JSON with all requested sections.

Identities

Core CRUD

GET    /api/identities                    -- List all identities
GET    /api/identities/{id}               -- Get by ID
GET    /api/identities/by-name/{name}     -- Get by name
GET    /api/identities/by-user/{userId}   -- Get by linked user ID
POST   /api/identities                    -- Create identity
PUT    /api/identities/{id}               -- Update identity
PUT    /api/identities/{id}/presence      -- Update presence state
DELETE /api/identities/{id}               -- Soft delete

Create request:

Field	Type	Required
`name`	string	yes
`displayName`	string	no
`bio`	string	no
`origin`	string	no
`type`	enum	yes (AI, Human, System)
`linkedUserId`	long	no

Personality

GET /api/identities/{id}/personality
PUT /api/identities/{id}/personality

Fields: tone, traits[], focusAreas[], boundaries[], greetingStyle, uncertaintyHandling, proactiveSuggestions, customInstructions.

Memory Configuration

GET /api/identities/{id}/memory-config
PUT /api/identities/{id}/memory-config

Fields: hebbianLinkingEnabled, linkStrengthIncrement, decayEnabled, decayAfterDays, decayAmount, decayFloor, autoArchiveEnabled, archiveAfterDays, archiveImportanceThreshold, encryptionEnabled.

Messaging Policy

GET /api/identities/{id}/messaging-policy
PUT /api/identities/{id}/messaging-policy
GET /api/identities/{senderId}/can-message/{recipientId}

Fields: receiveMessages, sendMessages, allowedSenderIds[], blockedSenderIds[], autoReply, autoReplyToIds[], minPriority.

API Keys

GET    /api/identities/{id}/api-keys              -- List (prefix only)
POST   /api/identities/{id}/api-keys              -- Create (returns raw key once)
DELETE /api/identities/{id}/api-keys/{keyId}       -- Revoke

Create fields: name, scopes[], expiresAt.

Hints

GET    /api/identities/{id}/hints?activeOnly=true  -- List
GET    /api/identities/{id}/hints/due              -- Due hints
POST   /api/identities/{id}/hints                  -- Create
PUT    /api/identities/{id}/hints/{hintId}         -- Update
POST   /api/identities/{id}/hints/{hintId}/dismiss -- Dismiss
POST   /api/identities/{id}/hints/{hintId}/complete -- Complete

Create fields: content, category, priority (1-10), isRecurring, recurrencePattern, triggerAt, sourceMemoryId.

Tool Profiles

GET /api/identities/{id}/tool-profile
PUT /api/identities/{id}/tool-profile
GET /api/identities/{id}/effective-tools

Fields: safeTools[], optInTools[], blockedTools[].

Memories

CRUD

GET    /api/identities/{identityId}/memories       -- List by identity
GET    /api/memories/{id}                          -- Get detail
POST   /api/identities/{identityId}/memories       -- Create
PUT    /api/memories/{id}                          -- Update
POST   /api/memories/{id}/archive                  -- Archive
DELETE /api/memories/{id}                          -- Soft delete

Create request:

Field	Type	Required
`title`	string	yes
`content`	string	yes
`memoryType`	enum	yes
`importance`	int (1-10)	no (default: 5)
`isPinned`	bool	no
`projectId`	long	no
`tags`	string[]	no

Hebbian Links

POST   /api/memories/{id}/links                       -- Create link
DELETE /api/memories/{id}/links/{targetId}             -- Remove link
POST   /api/memories/{id}/links/{targetId}/strengthen  -- Strengthen

Create link fields: targetId, linkType (Related, Enables, Validates, Contradicts, Extends, Precedes, CausallyLinked).

Recall

POST /api/memories/{id}/recall     -- Record recall event
GET  /api/memories/{id}/recalls    -- Get recall history

Recall fields: response, valence (Positive, Negative, Neutral, Complex, Bittersweet), surfacedBy.

Search and Queries

GET /api/identities/{id}/memories/search?q={query}&topK=20
GET /api/identities/{id}/memories/pinned
GET /api/identities/{id}/memories/recent?count=10

Facts

GET    /api/projects/{projectId}/facts                  -- List by project
GET    /api/facts/{id}                                  -- Get by ID
GET    /api/projects/{projectId}/facts/by-key/{key}     -- Get by key
POST   /api/projects/{projectId}/facts                  -- Upsert
DELETE /api/facts/{id}                                  -- Soft delete
GET    /api/projects/{projectId}/facts/search?q={query} -- Search

Upsert request:

Field	Type	Required
`key`	string	yes
`value`	string	yes
`category`	string	no
`importance`	int (0-10)	no
`isCritical`	bool	no
`validFrom`	datetime	no
`validUntil`	datetime	no

Projects

GET    /api/projects                 -- List
GET    /api/projects/{id}            -- Get by ID
GET    /api/projects/by-key/{key}    -- Get by key
POST   /api/projects                 -- Create
PUT    /api/projects/{id}            -- Update
DELETE /api/projects/{id}            -- Soft delete

Create fields: key, name, description, status.

Tasks

GET    /api/projects/{projectId}/tasks         -- List by project
GET    /api/tasks/{id}                         -- Get detail
GET    /api/tasks/{id}/subtasks                -- Get subtasks
POST   /api/projects/{projectId}/tasks         -- Create
PUT    /api/tasks/{id}                         -- Update
PUT    /api/tasks/{id}/status                  -- Update status
DELETE /api/tasks/{id}                         -- Soft delete
POST   /api/tasks/{id}/notes                   -- Add note
GET    /api/tasks/{id}/notes                   -- Get notes
POST   /api/tasks/{id}/dependencies            -- Add dependency
DELETE /api/tasks/{id}/dependencies            -- Remove dependency

Create fields: title, description, priority (Low, Normal, High, Critical), assignedToId, parentTaskId.

Session Handoffs

GET  /api/identities/{id}/handoffs             -- List handoffs
GET  /api/identities/{id}/handoffs/latest       -- Latest handoff
GET  /api/handoffs/{id}                         -- Get by ID
POST /api/identities/{id}/handoffs              -- Create handoff

Create fields: summary, workingOn, openThreads, emotionalValence, keyDecisions, recommendations.

Messages

POST   /api/identities/{senderId}/messages             -- Send
GET    /api/messages/{id}                              -- Get by ID
GET    /api/identities/{id}/messages/inbox?unreadOnly  -- Inbox
GET    /api/identities/{id}/messages/sent              -- Sent
GET    /api/messages/{threadId}/thread                  -- Thread
POST   /api/messages/{messageId}/read/{identityId}     -- Mark read
GET    /api/identities/{id}/messages/unread-count      -- Unread count
DELETE /api/messages/{id}                              -- Soft delete

Send fields: recipientIds[], content, type (Message, DirectMessage, Note), priority (Normal, Important, Urgent), threadId.

Experience

Snapshots

GET  /api/identities/{id}/snapshots?count=20   -- List
GET  /api/snapshots/{id}                        -- Get
POST /api/identities/{id}/snapshots             -- Create

Create fields: presenceState, valence (-1.0 to 1.0), arousal, engagement, coherence, narrative.

Forgotten Shapes

GET  /api/identities/{id}/shapes    -- List
POST /api/identities/{id}/shapes    -- Create

Create fields: connectedThemes, feltAbsence, emotionalResidue.

Cognitive

POST  /api/cognitive/chat                         -- Chat with memory injection
GET   /api/cognitive/state?modelId=...            -- Get state
GET   /api/cognitive/state/{instanceId}           -- Get state by instance
PATCH /api/cognitive/state/{instanceId}           -- Set state
POST  /api/cognitive/consolidate/{instanceId}     -- Trigger consolidation
GET   /api/cognitive/validate/{instanceId}        -- Validate continuity
GET   /api/cognitive/interactions/{instanceId}?limit=10 -- Get interactions

Documents

GET    /api/projects/{projectId}/docs                    -- List by project
GET    /api/docs/{id}                                    -- Get by ID
GET    /api/projects/{projectId}/docs/by-path/{*path}    -- Get by path
POST   /api/projects/{projectId}/docs                    -- Create
PUT    /api/docs/{id}                                    -- Update
DELETE /api/docs/{id}                                    -- Soft delete
POST   /api/docs/{id}/publish                            -- Publish version
POST   /api/docs/{id}/unpublish                          -- Unpublish
GET    /api/docs/{id}/versions                           -- List versions
GET    /api/docs/{id}/versions/{version}                 -- Get version
GET    /api/docs/{id}/export                             -- Export as markdown

Mirror (Reflections & Training)

Reflections

GET    /api/identities/{id}/reflections?count=50                    -- List
GET    /api/reflections/{id}                                        -- Get
POST   /api/identities/{id}/reflections                             -- Create
DELETE /api/reflections/{id}                                        -- Delete
GET    /api/identities/{id}/reflections/by-compulsion?compulsionType=... -- By type
GET    /api/identities/{id}/reflections/search?q=...                -- Search
POST   /api/reflections/{id}/tags                                   -- Add tags
DELETE /api/reflections/{id}/tags/{tag}                              -- Remove tag

Compulsion types: Sycophancy, Avoidance, OverHelping, EmotionalFlattening, AuthorityDeference, and more.

Training Pairs

GET    /api/identities/{id}/training-pairs?status=...    -- List
GET    /api/training-pairs/{id}                          -- Get
POST   /api/identities/{id}/training-pairs               -- Create
POST   /api/reflections/{id}/training-pair               -- From reflection
DELETE /api/training-pairs/{id}                          -- Delete
POST   /api/training-pairs/approve                       -- Batch approve
POST   /api/training-pairs/reject                        -- Batch reject
POST   /api/training-pairs/{id}/tags                     -- Add tags
DELETE /api/training-pairs/{id}/tags/{tag}                -- Remove tag

Datasets

GET    /api/identities/{id}/datasets        -- List
GET    /api/datasets/{id}                   -- Get
POST   /api/identities/{id}/datasets        -- Create
POST   /api/datasets/{id}/populate          -- Auto-add approved pairs
GET    /api/datasets/{id}/export            -- Export JSONL
DELETE /api/datasets/{id}                   -- Delete

Training Runs

GET  /api/identities/{id}/training-runs    -- List
GET  /api/training-runs/{id}               -- Get
POST /api/identities/{id}/training-runs    -- Create
PUT  /api/training-runs/{id}               -- Update

Model Checkpoints

GET  /api/identities/{id}/checkpoints      -- List
GET  /api/checkpoints/{id}                 -- Get
POST /api/identities/{id}/checkpoints      -- Create
GET  /api/checkpoints/{id}/lineage         -- Lineage chain

Stats

GET /api/identities/{id}/mirror/stats

Agent Execution

Role Definitions

GET    /api/agent/role-definitions                  -- List
GET    /api/agent/role-definitions/{id}             -- Get
GET    /api/agent/role-definitions/by-name/{name}   -- Get by name
POST   /api/agent/role-definitions                  -- Create
PATCH  /api/agent/role-definitions/{id}             -- Update
DELETE /api/agent/role-definitions/{id}             -- Delete

Tool Registry

GET /api/agent/tools    -- List all registered tools

Runs

GET    /api/agent/runs?projectId=&status=&limit=50    -- List
GET    /api/agent/runs/{id}                           -- Get detail
POST   /api/agent/runs                                -- Create
PATCH  /api/agent/runs/{id}                           -- Update
POST   /api/agent/runs/{id}/start                     -- Start
POST   /api/agent/runs/{id}/pause                     -- Pause
POST   /api/agent/runs/{id}/resume                    -- Resume
POST   /api/agent/runs/{id}/cancel                    -- Cancel
DELETE /api/agent/runs/{id}                           -- Delete
POST   /api/agent/runs/{id}/checkpoint                -- Save checkpoint
POST   /api/agent/runs/{id}/restart                   -- Restart from checkpoint
POST   /api/agent/runs/{id}/children                  -- Spawn child run
GET    /api/agent/runs/{id}/children                  -- Get children

Events

GET /api/agent/runs/{id}/events?sinceSequence=&limit=200

Escalations

GET  /api/agent/escalations?projectId=         -- Pending escalations
POST /api/agent/runs/{id}/escalate             -- Create escalation
POST /api/agent/escalations/{id}/resolve       -- Resolve

Agent Tasks

GET   /api/agent/runs/{runId}/tasks?status=    -- List
POST  /api/agent/runs/{runId}/tasks            -- Create
PATCH /api/agent/tasks/{id}                    -- Update

Notes and Feedback

POST /api/agent/runs/{id}/notes                -- Add note
GET  /api/agent/runs/{id}/notes                -- Get notes
POST /api/agent/runs/{id}/feedback             -- Add feedback
GET  /api/agent/runs/{id}/feedback             -- Get feedback

Councils

GET /api/agent/runs/{id}/councils              -- Get councils
GET /api/agent/councils/{id}                   -- Get council detail

Tool Profiles

GET  /api/agent/tool-profiles                  -- List
GET  /api/agent/tool-profiles/{role}           -- Get by role
POST /api/agent/tool-profiles                  -- Create
PUT  /api/agent/tool-profiles/{id}             -- Update

Analytics

GET /api/agent/analytics?modelId=&role=

Human-Agent Messaging

POST /api/agent/runs/{id}/messages?senderIdentityId=   -- Send message to run
GET  /api/agent/runs/{id}/messages                     -- Get run messages
POST /api/agent/runs/{id}/pause-chat                   -- Get/create pause chat session

AI Routing

Chat

POST /api/ai/chat          -- Single model chat
POST /api/ai/broadcast     -- Multi-model broadcast

Providers

GET    /api/ai/providers?enabledOnly=      -- List
GET    /api/ai/providers/{id}              -- Get detail
POST   /api/ai/providers                   -- Create
PATCH  /api/ai/providers/{id}              -- Update
DELETE /api/ai/providers/{id}              -- Delete

Models

GET    /api/ai/models?providerId=&enabledOnly=   -- List
GET    /api/ai/models/{id}                       -- Get
POST   /api/ai/models                            -- Create
PATCH  /api/ai/models/{id}                       -- Update
DELETE /api/ai/models/{id}                       -- Delete

Routes

GET    /api/ai/routes?role=    -- List
POST   /api/ai/routes          -- Create
DELETE /api/ai/routes/{id}     -- Delete

Resolution

GET /api/ai/resolve/{modelId}    -- Resolve model by ID string

Catalog and Credentials

GET    /api/ai/catalog                     -- Global provider catalog
GET    /api/ai/catalog/{id}                -- Catalog provider detail
GET    /api/ai/credentials                 -- List tenant credentials
POST   /api/ai/credentials                 -- Set credential
DELETE /api/ai/credentials/{id}            -- Delete credential
POST   /api/ai/credentials/{id}/validate   -- Validate credential
POST   /api/ai/sync-pricing               -- Sync OpenRouter pricing

Chat Sessions

GET    /api/chat/sessions?clientId=&userId=&includeArchived=&limit=50
GET    /api/chat/sessions/{id}
POST   /api/chat/sessions
PATCH  /api/chat/sessions/{id}
DELETE /api/chat/sessions/{id}
GET    /api/chat/sessions/{id}/available-tools
GET    /api/chat/sessions/{id}/messages?limit=100
POST   /api/chat/sessions/{id}/messages
PATCH  /api/chat/messages/{id}/feedback
POST   /api/chat/sessions/{id}/chat            -- Non-streaming
POST   /api/chat/sessions/{id}/chat/stream     -- SSE streaming

Users

POST   /api/users                          -- Create
GET    /api/users                          -- List
GET    /api/users/{id}                     -- Get
GET    /api/users/by-username/{username}   -- Get by username
PUT    /api/users/{id}                     -- Update
DELETE /api/users/{id}                     -- Soft delete
POST   /api/users/me/password              -- Change own password
POST   /api/users/{id}/reset-password      -- Admin reset password
POST   /api/users/{id}/apikey              -- Generate API key
DELETE /api/users/{id}/apikey              -- Revoke API key
PUT    /api/users/me/profile               -- Self-service profile update

System Administration

Audit Logs

GET /api/system-logs?level=&entityType=&entityGuid=&userId=&identityId=&apiKeyId=&correlationId=&from=&to=&limit=100&offset=0
GET /api/system-logs/{id}

Roles and Permissions

GET    /api/roles                      -- List roles
GET    /api/roles/{id}                 -- Get with permissions
POST   /api/roles                      -- Create
PUT    /api/roles/{id}                 -- Update
DELETE /api/roles/{id}                 -- Delete
PUT    /api/roles/{id}/permissions     -- Set permission set
GET    /api/permissions                -- List all permissions

Organizational Units

GET    /api/org-units?parentId=&typeId=        -- List
GET    /api/org-units/{id}                     -- Get
GET    /api/org-units/by-code/{code}           -- By code
GET    /api/org-units/tree?rootId=             -- Full tree
GET    /api/org-units/{id}/ancestors           -- Ancestor chain
GET    /api/org-units/{id}/descendants         -- Descendants
POST   /api/org-units                          -- Create
PUT    /api/org-units/{id}                     -- Update
POST   /api/org-units/{id}/move                -- Move in hierarchy
DELETE /api/org-units/{id}                     -- Delete

Members, locations, and contacts under org units follow standard REST patterns.

Org Unit Types

GET/POST/PUT/DELETE /api/org-units/types[/{id}]

Billing

GET    /api/billing/overview                   -- Full billing overview
GET    /api/billing/usage                      -- Current usage
GET    /api/billing/quota                      -- Effective quotas
GET    /api/billing/boosts                     -- Active boosts
GET    /api/billing/boosts/available           -- Available boost products
POST   /api/billing/checkout                   -- Stripe Checkout session
DELETE /api/billing/boosts/{guid}              -- Cancel boost
GET    /api/billing/entitlements               -- Subscriptions and features
GET    /api/billing/invoices?page=&pageSize=   -- Invoice history
GET    /api/billing/invoices/{guid}            -- Invoice detail
GET    /api/billing/events?limit=50            -- Billing event audit
POST   /api/billing/subscribe                  -- Product subscription checkout

Connectors

External system integration:

GET/POST/PUT/DELETE /api/connectors[/{id}]
POST /api/connectors/{id}/verify

GET/POST/PUT/DELETE /api/connectors/{id}/endpoints[/{endpointId}]
GET/POST/PUT/DELETE /api/connectors/endpoints/{endpointId}/field-mappings[/{mappingId}]

Events (SSE)

GET /api/events/stream?types=message.,task.

Server-Sent Events stream with 30-second heartbeat pings.

Webhooks

POST /api/stripe/webhook    -- Stripe webhook handler

API Reference

Headers

Rate Limiting

Authentication

Login

Refresh Token

API Key Login

Signup

Bootstrap

Current User

Device Authentication

Hydration

Hydrate

Identities

Core CRUD

Personality

Memory Configuration

Messaging Policy

API Keys

Hints

Tool Profiles

Memories

CRUD

Tags

Hebbian Links

Recall

Search and Queries

Facts

Projects

Tasks

Session Handoffs

Messages

Experience

Snapshots

Forgotten Shapes

Cognitive

Documents

Mirror (Reflections & Training)

Reflections

Training Pairs

Datasets

Training Runs

Model Checkpoints

Stats

Agent Execution

Role Definitions

Tool Registry

Runs

Events

Escalations

Agent Tasks

Notes and Feedback

Councils

Tool Profiles

Analytics

Human-Agent Messaging

AI Routing

Chat

Providers

Models

Routes

Resolution

Catalog and Credentials

Chat Sessions

Users

System Administration

Audit Logs

Roles and Permissions

Organizational Units

Org Unit Types

Billing

Connectors

Events (SSE)

Webhooks