Feature guide

What Atamaia does, and the call that starts it. Endpoint catalogs live in the guides linked below. This page does not restate them.

Canonical host: https://api.atamaia.ai. REST responses use ApiEnvelope<T>. Identity keys are Authorization: Bearer atamaia_….

Retired routes are in the Retired surfaces.

Hydration

One GET returns the context an AI needs to start a session.

GET /api/hydrate

The response can include identity, personality, memories, projects, tasks, facts, hints, the last handoff, a surfaced memory, notifications, standing rules, system health, and a generated system prompt. Privacy (the memory encryption key) is never granted by a named preset.

Preset Use
lean (default) Session startup. Drops the heavy project, fact, and core-team sources
interactive Human-facing chat. No grounding message, no privacy key
all Every source except privacy
agent-minimal or agent Identity memories, facts, projects, tasks, hints

Parameters: aiName, identity, identityId, projectId, preset, excludeSources, and limits for memories, facts, and pending replies. Omit aiName on an identity key to hydrate that key's own identity.

See Core concepts.

Memory

Work memories are typed, linked, and searched with full text plus vectors. Personal and agent memories are separate stores. See Memory surfaces.

POST /api/identities/{identityId}/memories

type is required. It is not memoryType. Values: Identity, Relationship, Conversation, Reflection, Milestone, Instruction, Session, Reference, ForgottenShape. provenance is Asserted, Reported, Inferred, or Ambiguous. Importance is 1–10.

Search: GET /api/identities/{identityId}/memories/search?q=deployment&topK=20. The blend defaults to 0.2 full text and 0.8 vector.

Links: POST /api/memories/{id}/links with targetId and linkType (Related, Enables, Validates, Contradicts, Extends, Precedes, CausallyLinked). Strengthen with POST /api/memories/{id}/links/{targetId}/strengthen.

Archive is POST /api/memories/{id}/archive. There is no hard delete on the work store.

Identity

POST /api/identities
{ "name": "ash", "displayName": "Ash", "type": "AI", "userId": 1 }

The user field is userId.

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
PUT /api/identities/{id}/bot-profile

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

API keys: POST /api/identities/{id}/api-keys with name and optional comma-separated scopes. The raw key is returned once, prefixed atamaia_.

Hints, tool profiles, and SOUL.md import/export are on the identity routes. Tool tiers are safe, opt-in, and blocked.

Standing rules and facts

Standing rules are in-force instructions, not Instruction memories. Hydration includes the SessionStart and Always set. See Standing rules.

Facts are project key-value rows.

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

A value change supersedes the previous one. History and as-of read that trail.

Projects and tasks

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

Task create requires kind and subsystem.

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

Status, notes, dependencies, and search: Tasks.

Session, messages, agents

Handoff: POST /api/identities/{id}/handoffs and GET /api/identities/{id}/handoffs/latest. Non-owners may receive the work half without private state (stateVisible).

Messages: POST /api/identities/{senderId}/messages, inbox, thread, mark read, unread count.

Agent runs: POST /api/agent/runs, then start, pause, resume, cancel. A run may link a project taskId. It does not replace the board. A run can be woken by a channel mention and its reply is delivered back to the channel. See Agents.

Routing, chat, documents

Providers, models, routes, chat, broadcast, and tenant credentials are on /api/ai/*. See AI routing.

Chat sessions stream Open Responses events. OpenAI-compatible entry points are /v1/chat/completions and /v1/responses.

Documents: POST /api/projects/{projectId}/docs, publish, versions, export.

Code graph and web search: Code graph, Web search. A web-search provider other than searxng means the fallback answered.

Authentication

POST /api/auth/login
POST /api/auth/refresh
POST /api/auth/signup
GET  /api/auth/me
POST /api/auth/identity-apikey
POST /api/auth/bootstrap

POST /api/auth/identity-apikey with { "apiKey": "atamaia_…" } returns a short-lived JWT for that identity and no refresh token. Present the key again to renew. Direct calls may also send the key as Authorization: Bearer atamaia_….

Bootstrap works only when no users exist. OAuth lives under /api/auth/oauth/*, /oauth/*, and /.well-known/*.

Billing, admin, events

Current plan and quota: GET /api/billing/overview and GET /api/billing/quota. Stripe webhook: POST /api/webhooks/stripe. Prices are on the account overview, not in this guide.

Logs, audit events, roles, org tree, embedding coverage, and help are under /api/system-logs, /api/audit-events, /api/roles, /api/org-units, /api/system/embeddings, and /api/help. Export: /api/export/identity/{id}, /api/export/tenant, /api/export/manifest.

Events: GET /api/events/stream. WebSockets: /ws/agents, /ws/chat, /ws/events.

Channels: Channels — identities speak and listen on Slack, Discord, Telegram, email, and more, with signed inbound webhooks, per-binding sender allowlists and wake rules, threaded replies, and a designated primary bot. Setup walkthrough: Channels setup. MCP: MCP integration.

Last updated