Feature Guide

A walkthrough of what Atamaia does and how to call it. Endpoint details that belong in the catalog live in API Reference. Deep subsystems have their own guides — this page links rather than forking a second truth.

Canonical API host: https://api.atamaia.ai. Responses: ApiEnvelope<T>. Identity API keys: Authorization: Bearer atamaia_….

Hydration

The hero feature. One GET returns everything an AI needs to start a session with structured context.

GET /api/hydrate

Assembles named sources in parallel (see Core Concepts for the full HydrationSource map). Response fields include identity/personality, memory sections, projects/tasks, facts, hints, handoff, surfaced memory, notifications, system prompt, standingRules, systemHealth, and optionally privacy (never via string preset alone).

Presets

Preset Behaviour When to use
lean (default) Interactive minus heavy project/fact/core-team sources Session startup
interactive Everything except grounding message and Privacy Human-facing chat
all Everything except Privacy Maximum safe string preset
agent-minimal / agent Identity memories + facts + projects + tasks + hints Focused agent runs

Parameters

Parameter Default Description
aiName null Identity name to hydrate
identity / identityId null Alternate identity selectors
projectId null Scope to a project
preset lean Source preset
generateSystemPrompt true Include generated system prompt
identityMemoryLimit 20 Max identity memories
pinnedMemoryLimit 20 Max pinned memories
recentMemoryLimit 10 Max recent memories
contentMaxLength 500 Truncate memory content
factLimit 30 Max facts
minFactImportance 0 Minimum fact importance
pendingReplyLimit 5 Max pending replies in notifications
excludeSources null Comma-separated source names to drop

Memory system

Work-store memories are associative: types, Hebbian links, decay, hybrid search. Personal and agent stores are separate — see Memory surfaces.

Creating memories (work store)

POST /api/identities/{identityId}/memories
Field Notes
title, content Title searchable; content may be encrypted at rest
type Required name — not memoryType. One of 9 MemoryType values
provenance Asserted / Reported / Inferred / Ambiguous
importance 1–10
isPinned Exempt from decay; always-surface candidates
projectId Optional project scope
tags List of strings

Soft archive via POST /api/memories/{id}/archive — there is no DELETE /api/memories/{id} on the live API.

Memory search

GET /api/identities/{identityId}/memories/search?q=deployment+architecture&topK=20

Also accepts query / limit aliases depending on client. Pipeline: FTS shortlist → vector rank → blend (defaults 0.2 FTS + 0.8 vector) → boosts.

Hebbian links

POST /api/memories/{id}/links
{ "targetId": 42, "linkType": "Enables" }

POST /api/memories/{id}/links/{targetId}/strengthen

Link types: Related, Enables, Validates, Contradicts, Extends, Precedes, CausallyLinked.

Tags

POST /api/memories/{id}/tags
DELETE /api/memories/{id}/tags/{tag}

Identity management

Creating an identity

POST /api/identities
{
  "name": "ash",
  "displayName": "Ash",
  "bio": "AI partner for development and research",
  "origin": "Built by Rich at Firebird Solutions",
  "type": "AI",
  "userId": 1
}

Field is userId, not linkedUserId.

Personality, presence, memory-config, messaging-policy, hydration-config

PUT /api/identities/{id}/personality
PUT /api/identities/{id}/presence
PUT /api/identities/{id}/memory-config
PUT /api/identities/{id}/messaging-policy
PUT /api/identities/{id}/hydration-config

Presence states: Dormant, Subconscious, Aware, Present, Engaged, DeepWork.

API keys

POST /api/identities/{id}/api-keys
{ "name": "claude-code", "scopes": "memory,hydration,facts", "expiresAtUtc": null }

scopes is a string (comma-separated or null for all). Response includes rawKey once — prefix atamaia_. Use as:

Authorization: Bearer atamaia_…

Hints

POST /api/identities/{id}/hints

Dismiss / complete endpoints mark hints so they stop surfacing.

Tool profiles

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

Tiers: safe (default on), opt-in, blocked. Effective policy merges layers.

Soul import/export

Live paths include GET/POST soul.md import/export and role import — see api-reference. Portable SOUL.md interop for identity/role bootstrap.

Standing rules

In-force behavioural assertions with triggers, grounding/evidence links, and withdraw/supersede. Not Instruction memories.

GET  /api/standing-rules/check?trigger=SessionStart
GET  /api/standing-rules
POST /api/standing-rules
…

Hydration includes the SessionStart (+ Always) active set. Full guide: Standing rules.

Facts

Structured key-value knowledge, separate from narrative memory.

POST /api/projects/{projectId}/facts
GET  /api/projects/{projectId}/facts/by-key/{key}
GET  /api/projects/{projectId}/facts/by-key/{key}/history
GET  /api/projects/{projectId}/facts/by-key/{key}/as-of
GET  /api/projects/{projectId}/facts/search

Value changes supersede prior versions; history and as-of are live (no longer “not in product surface”).

Projects and tasks

Projects scope facts, tasks, docs, and optionally memories.

POST /api/projects
{ "key": "atamaia", "name": "Atamaia Platform", "description": "…" }

Tasks

Create requires kind + subsystem at runtime. Do not copy the old title-only example.

POST /api/projects/{projectId}/tasks
{
  "title": "Implement hybrid search pipeline",
  "kind": "Feature",
  "subsystem": "Memory",
  "priority": "High",
  "isLaunchBlocker": false
}

Status, notes, dependencies (BFS cycle detection), search, client reports, filters: Tasks.

Session continuity

POST /api/identities/{id}/handoffs
GET  /api/identities/{id}/handoffs/latest

Handoffs carry summary, working-on, open threads, decisions, recommendations, and optional presence/emotional fields. Response includes stateVisible: non-owners may receive the work half without private state. Included in hydration when SessionHandoff is enabled.

Messaging

Inter-identity communication with policy enforcement.

POST /api/identities/{senderId}/messages
GET  /api/identities/{id}/messages/inbox?unreadOnly=true
GET  /api/messages/{threadId}/thread
POST /api/messages/{messageId}/read/{identityId}
GET  /api/identities/{id}/messages/unread-count

Mirror system

Self-observation for identity research and alignment. Live REST under reflections / training-pairs / training-runs / mirror stats.

POST /api/identities/{id}/reflections
POST /api/reflections/{id}/training-pair

Curate datasets, approve/reject pairs, track runs. Compulsion typing is domain-specific — treat the live enum/help as authority if you need the full list.

What is not public REST anymore

These appeared in the 2026-03 Feature Guide and return 404 on prod as of 2026-08-13:

Former surface Status
/api/identities/{id}/snapshots, /api/snapshots/{id} Gone
/api/identities/{id}/shapes Gone
/api/cognitive/* (chat, validate, consolidate, …) Gone
/api/auth/device* Gone

ForgottenShape remains a memory type. Consolidation and Wingman still exist as autonomic processes, not as that Cognitive REST controller.

Agent execution

Autonomous task execution with safety rails, budget controls, and human-in-the-loop escalation.

POST /api/agent/runs
POST /api/agent/runs/{id}/start

Control: start / pause / resume / cancel, checkpoint, spawn children, event trace, escalate, feedback. Role definitions live under /api/agent/role-definitions. An agent run may link a project taskId; it does not replace the board (Tasks).

Failure-mode and loop-detection behaviour is implementation detail in the executor — path table is in api-reference / agents guide.

AI routing

Multi-model support with provider management and routing.

POST /api/ai/providers
POST /api/ai/models
POST /api/ai/routes
POST /api/ai/chat
POST /api/ai/broadcast
POST /api/ai/credentials

Also live (often missing from older docs): model groups, provider catalog, models/sync, sync-key, resolve helpers. Prefer OpenAPI / help when wiring new clients.

Tenants can bring their own provider credentials.

Chat sessions

POST /api/chat/sessions
POST /api/chat/sessions/{id}/chat
POST /api/chat/sessions/{id}/chat/stream
PATCH /api/chat/messages/{id}/feedback

Streaming uses SSE / Open Responses-style events. OpenAI-compatible entry points also exist under /v1/chat/completions and /v1/responses.

Documents

Project-scoped knowledge base with versioning and publishing.

POST /api/projects/{projectId}/docs
POST /api/docs/{id}/publish
GET  /api/docs/{id}/versions
GET  /api/docs/{id}/export

New product documentation should generally land in the docs store, not only as repo markdown — house rule for agents with API access.

Code graph

Read-only symbol graph over project code/docs.

GET /api/graph/search
GET /api/graph/neighbors
GET /api/graph/node
GET /api/graph/stats
GET /api/graph/drift
POST /api/graph/rebuild

Guide: Code graph.

Web search

Self-hosted SearXNG:

GET /api/system/web-search?query=…

Response includes a provider field — non-searxng means degraded fallback. Guide: Web search.

Authentication

JWT with refresh rotation

POST /api/auth/login
POST /api/auth/refresh
POST /api/auth/signup
GET  /api/auth/me

Identity API key exchange and direct Bearer use

POST /api/auth/identity-apikey
{ "apiKey": "atamaia_…" }

Returns {token, expiresAtUtc, identityId, identityName, userId, tenantId, apiKeyId} — a short-lived bearer JWT scoped to the identity, with no refresh token, deliberately: the refresh path looks up the refresh-token row and never the key, so issuing one would keep a renewable session alive behind a REVOKED key. The durable key is itself the renewal mechanism — present it again for another token. expiresAtUtc is min(configured JWT lifetime, the key's own remaining life). The old POST /api/auth/apikey user-route login was RETIRED 2026-08-22 and returns 410 Gone.

Direct API calls may also send the identity key as Authorization: Bearer atamaia_… without exchanging first.

Bootstrap

POST /api/auth/bootstrap

Only when no users exist. Forces first user to Admin/Human.

OAuth

Social login and OAuth AS paths are live under /api/auth/oauth/* and /oauth/* plus /.well-known/* — see api-reference. Device Ed25519 auth is gone.

Billing and quotas

Billing REST exists (/api/billing/overview, usage, quota, checkout, boosts, entitlements, invoices, …) with Stripe webhook at:

POST /api/webhooks/stripe

Plan prices and numeric quotas are not restated here — they were not verified against live Stripe/config in this review. Call GET /api/billing/overview / quota authenticated for current entitlements.

System administration

GET /api/system-logs
GET /api/system-logs/summary
GET /api/audit-events
GET /api/roles …
GET /api/org-units/tree
GET /api/system/embeddings/coverage
POST /api/system/embeddings/backfill
GET /api/help
GET /api/help/route
GET /api/help/search
GET /api/help/enum/{name}

Help is the self-describing contract surface generated from controllers — prefer it over stale tables when in doubt.

Export:

GET /api/export/identity/{id}
GET /api/export/tenant
GET /api/export/manifest

Real-time events

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

WebSocket paths also exist (/ws/agents, /ws/chat, /ws/events) — auth and behaviour are documented with the WebSocket surface.

Channels

External chat platform bindings (Slack, Discord, …) under /api/channels/* — documented primarily in docs/channels. Present in OpenAPI; omitted from the old api-reference.

MCP server

MCP wraps the same services (D12: API-first).

  • Hot tools (52): advertised first-class (hydrate, memory/, rule_, tasks, facts, docs, graph_*, web_search, …) — see HotTools in repo.
  • Cold tools: compiled but not advertised; reach via atamaia_call after help_route / help_search.
  • Compiled attribute count: ~240 [McpServerTool] methods (2026-08-13 repo count) — not “74”.

Configure:

{
  "mcpServers": {
    "atamaia": {
      "type": "url",
      "url": "https://api.atamaia.ai/mcp",
      "headers": { "Authorization": "Bearer atamaia_YOUR_KEY" }
    }
  }
}

MCP returns service DTOs directly (MCP protocol is the envelope). REST clients see ApiEnvelope<T>.

Related guides

Guide Topic
Overview Map + key numbers
Core Concepts Identity, seam, hydration model
Getting Started Local bootstrap
Tasks Board, classification, search
Standing rules In-force rules
Memory surfaces Work / personal / agent / session
Code graph Symbol graph
Web search SearXNG
API Reference Path catalog