REST API reference

This page lists every HTTP route a Dakera v0.12.3 server exposes, grouped by area, with the request fields, status codes and permission scopes that matter when you call it directly. It is for developers writing their own client or checking what an SDK sends; if you use a language SDK or the MCP server, treat it as the reference behind those.

Authentication is on by default. Every route except /health, /health/live, /health/ready and /metrics needs an API key, sent as Authorization: Bearer <key> or X-API-Key: <key>. With authentication on and no key configured, the server refuses to start; set DAKERA_ROOT_API_KEY to create the first key. Since v0.12 the gRPC port takes the same keys as call metadata.

Health

GET /health answers status (healthy or degraded), version, build_sha, unreadable_records and corrupt_records, degraded (every degraded component with a reason; always present), config_warnings (configuration the node started with although it is not what it should be; informational, never makes the node degraded), embed_migration (progress of the one-time re-embed of stored memories) and, in a cluster, clock_ahead_ms while this node's clock is too far ahead of its peers. While starting it answers 503 with "status": "starting", a reason and downloads (each model file with received_bytes and total_bytes). Reasons never contain file paths or credential URLs. dakera --check-config prints the warnings before a start; see Operations.

Capabilities

{
  "capabilities_version": 2, "server_version": "0.12.3", "default_model": "bge-large",
  "models": [ { "name": "bge-m3", "dimension": 1024, "max_seq_length": 8192,
                "effective_max_seq_length": 2048, "active": false, "modality": "text" }, ... ],
  "live_vector_index_kinds": ["hnsw"], "search_mode": "hybrid", "fulltext_language": "en",
  "query_languages": ["en", "de", "fr", "es", "it", "pt", "nl"],
  "records":     { "enabled": false, "representation_kinds": ["dense", "token_multivector", "patch_multivector"],
                   "dtypes": ["f32", "f16", "i8"], "max_representations": 8, "max_vectors": 4096, "max_bytes": 8388608 },
  "scoring":     { "strategy": "single-vector", "late_interaction": { "enabled": false, "model_supported": false, "lane": "text" } },
  "attachments": { "enabled": false, "max_bytes": 26214400, "transcription": { "model": "whisper-tiny.en" } },
  "vision":      { "enabled": false, "model": "colmodernvbert", "media_types": ["image/png"], "dimension": 128 },
  "reembed_pending": false,
  "sessions":    { "idle_timeout_secs": 14400, "max_idle_timeout_secs": 2592000, "touch": true, "ended_reason": true }
}

Authentication

Memory

Store memory — request body

{
  "agent_id": "my-agent",                  // required
  "content": "User prefers dark mode",       // required
  "importance": 0.8,                         // optional, 0.0–1.0, default 0.5
  "tags": ["preference", "ui"],             // optional
  "session_id": "sess-abc123",              // optional
  "memory_type": "episodic",                 // episodic | semantic | procedural | working
  "lang": "de",                               // optional (v0.12): en, de, fr, es, it, pt, nl; unsupported = 400
  "attachment_ref": "sha256:…",               // optional (v0.12, DAKERA_ATTACHMENTS): an uploaded attachment
  "event_time": "2024-05-07T18:30:00Z"     // optional (v0.12.3): when the event happened, Unix seconds or RFC 3339
}

Other optional fields: id, metadata, ttl_seconds, expires_at. From v0.12.2 every memory write path (store, batch, update, import, transcribe, index) checks: content at most DAKERA_MAX_MEMORY_CONTENT_BYTES UTF-8 bytes (default 100000; on update, a memory already above it may be updated to content no larger than it is now); metadata a JSON object (or null) of at most 100 top-level fields with keys of 1 to 256 bytes; no dakera-curated tag and no _dakera_* metadata key other than _dakera_content_date (integer, unix seconds) and _dakera_lang; no caller id of the form mem_s + 24 hex; ttl_seconds at most 100 years; agent ids at most 241 bytes. When the memory has a session, the store response carries session_state (active or ended; storing into an ended session still succeeds) and the batch response lists ended_sessions. lang selects how event dates, rule-based entity tags and full-text date metadata are parsed and is recorded as _dakera_lang; see Multilingual search.

event_time (v0.12.3), on a store and on each item of a batch store, records when the memory's event happened (Unix seconds or an RFC 3339 timestamp, from 1970 to 2286; otherwise 400 naming the field). Recency, since / until, the time range inferred from a query, the neighbourhood, supersession and the order of events read it instead of the ingest time, so an imported or replayed history reasons about time from its own dates. created_at stays the ingest time (TTL, decay, listings). Request fields the server does not know are still accepted; from v0.12.3 store, batch store, recall and batch recall name them in a warnings array and an X-Dakera-Ignored-Fields header.

Recall — request body

{
  "agent_id": "my-agent",                  // required
  "query": "UI preferences",                // required
  "top_k": 10,                               // optional, default 10, at most 10000
  "lang": "fr",                               // optional (v0.12): language of the query, for routing and dates
  "rerank": true,                             // optional, default true: cross-encoder rerank
  "rerank_candidates": 20,                    // optional (v0.12): score at most 20 candidates with the cross-encoder
  "min_importance": 0.5,                    // optional filter
  "tags": ["preference"],                    // optional filter
  "session_id": "sess-abc123",              // optional: scope to session
  "neighborhood_mode": "separate",         // optional (v0.12.3): inline (default) | separate | off
  "include_summaries": true                // optional (v0.12.3): may session summaries be recalled
}

The recall response carries memories[] (each with score, weighted_score, smart_score), query_embedding_time_ms, search_time_ms, rerank_report and, under late interaction, late_interaction_first_stage. rerank_report is {"applied": true, "candidates": 15}, or {"applied": false, "candidates": 0, "skipped": "…"} with skipped one of disabled, bm25_routing, visual_lane, no_candidates, no_query, unavailable, failed or low_confidence. rerank_candidates is capped by the server-wide DAKERA_RERANK_MAX_CANDIDATES; from v0.12.3, unset means the pool a top_k 10 recall builds (195 pairs with the default settings, 0 = no cap), rerank_report.capped is true when the cap applied, and rerank_candidates: 0 is a 400. A recall no longer raises the importance of the memories it returns, so smart_score values changed scale from v0.11; see Upgrading. At most two recalls per CPU core (at least four) run at once; the rest queue and, from v0.12.3, answer 429 with Retry-After after DAKERA_ADMISSION_WAIT_SECS (default 20 s; 503 before v0.12.3). Recall and search for an agent that has stored nothing answer 200 with no memories. Details: Search and ranking.

Ranking and session context (v0.12.3)

Each result carries rank_score, the score the results are ordered by: it never rises down memories, so sort or threshold on it. score keeps its meaning (the reranker's or retrieval score) and can rise down the list. The first k results of a recall with top_k = k are the first k of a top_k = 10 recall for every k up to 10 (DAKERA_RECALL_RANK_DEPTH), so asking for more results never reorders the head.

neighborhood_mode decides where the neighbouring memories of the top results' sessions go: inline (the default, as before: after the top_k ranked results, each marked retrieval: "neighborhood"), separate (in context_memories, each entry with context_of, the ranked memory it belongs to, so memories holds at most top_k) or off. neighborhood: false still means off. The server default is DAKERA_NEIGHBORHOOD_MODE. A document chunk's neighbours are the chunks before and after it. With DAKERA_RECALL_COLLAPSE_DERIVED=1 a sentence sub-memory and its source share one result, returned as the source with matched_text and matched_ids.

Document import v0.12.3

PDF, DOCX, HTML, Markdown and plain text become chunk memories of an agent that recall can cite. Chunking follows the document's structure (sections at headings, then paragraphs, sentences and words; code blocks and table rows kept whole while they fit), stays within the embedding model's token budget with an overlap, and every chunk carries _dakera_document metadata: document id, title, page range, heading path, chunk index and count. Re-importing a document id keeps unchanged chunks; an import that fails leaves the earlier version as it was. PDF and DOCX are parsed in a sandboxed child process. On by default (DAKERA_DOCUMENTS); GET /v1/capabilities reports documents.

{
  "agent_id": "support-bot",
  "content": "# Install\n\nRun the installer, then …",
  "media_type": "text/markdown",
  "title": "Field manual",
  "chunking": { "max_tokens": 400, "overlap_tokens": 50, "strategy": "structure" }
}

A file that cannot be parsed fails its job with 422 (UNPROCESSABLE_CONTENT), a parse that runs too long with 504 (EXTRACTION_TIMEOUT), and a document over the size or chunk limits with 413. Limits and defaults: Configuration.

Sessions

Authorization (v0.12.2). Sessions are authorized by their agent's namespace (_dakera_agent_{agent_id}) alone: a key needs no _dakera_sessions grant (such an entry is accepted and grants nothing).

Idle sessions end by themselves (v0.12.2). A session whose last activity is at least its timeout ago (its own idle_timeout_secs, else DAKERA_SESSION_IDLE_TIMEOUT_SECS, default 14400 = 4 h, 0 = off) is ended by the server exactly as a client end would, with ended_reason: "idle". Activity is a memory stored, batch-stored, imported or updated with the session, a session-scoped recall, search or batch recall, or touch. Sessions carry last_activity_at, ended_reason (client | idle; sessions ended before v0.12.2 read client), idle_since (idle ends) and idle_timeout_secs (when the session set its own).

Batch & advanced memory

Agents

Feedback

Vectors

From v0.12.2 the raw vector routes of an agent namespace (vectors, upsert-columns, records, upsert-text and gRPC Upsert) refuse a payload carrying _dakera_type and refuse to replace an existing memory record; vectors/bulk-update refuses an update that sets _dakera_type or selects a memory record (400, pointing at /v1/memory/*). Plain vectors in agent namespaces and every payload in other namespaces are unaffected.

Full-text & hybrid search

Text inference (auto-embedding)

Attachments & records opt-in, v0.12

Off by default. A server that has not enabled a feature answers its routes 501 FEATURE_DISABLED with the variable that turns it on. Attachments need DAKERA_ATTACHMENTS, image indexing also DAKERA_VISION, and records DAKERA_RECORDS. See Multimodal memory and Records and multi-vector.

A memory references an attachment with attachment_ref on POST /v1/memory/store; the attachment must have been uploaded to the memory's own namespace _dakera_agent_{agent_id} (otherwise 404). The transcription and image jobs read an attachment from any namespace the key can read and copy it into the agent's. Representation kind is dense, token_multivector or patch_multivector; store_as is f32 (default, lossless), f16 or i8; one record holds at most 8 extra representations, DAKERA_RECORD_MAX_VECTORS (default 4096) vectors per representation and DAKERA_RECORD_MAX_BYTES (default 8 MiB) in all, and over a limit is 413. A record upsert replaces the whole record; there is no record delete route, delete the id through the vector routes.

Jobs return 202 and are polled: status is Pending, Running, Completed or Failed, a failed job carries error: {status, code}, and job ids (job_<run>_<n>) are unknown after a restart (404 JOB_NOT_FOUND; the stored memory is kept, find it by memory_id). Every media job reserves its estimated peak memory first; if it does not fit within 10 s the answer is 503 with Retry-After.

Namespaces

Namespace API keys

Knowledge graph

Knowledge operations

From v0.12.3 deduplication (POST /v1/knowledge/deduplicate without dry_run, and AutoPilot in merge mode) and consolidation delete softly: each removed memory stays restorable for DAKERA_AUTOPILOT_TRASH_RETENTION_HOURS (default 168, 0 = no copy) and every removal is an audit event (deduplicated or consolidated; a restore is restored). AutoPilot deduplication is off by default (DAKERA_AUTOPILOT_DEDUP_MODE: off, report or merge).

Entity extraction

Import & export

Audit & events

From v0.12.2 open streams re-check their key every 15 s: a stream closes when the key is deleted, deactivated or expired, or no longer has the scope and namespaces the stream needs. session_ended events carry reason (client | idle).

Analytics & operations

Operations (/ops)

All need a global admin key (no namespace restriction).

Admin — cluster

Admin — API keys

Admin — storage & indexes

Admin — AutoPilot, decay & config

Admin — quotas

Admin — backup & recovery

Admin — namespaces

Admin — monitoring

Errors

Since v0.12 every error body is JSON with the same shape, including refusals made before a handler runs:

{ "error": "Namespace not found: unknown", "code": "NAMESPACE_NOT_FOUND", "status": 404,
  "details": "namespace: unknown", "resource": "namespace" }

details is optional; resource appears on 404 bodies. Error text never carries backend text such as object-store keys or file paths. The authentication layer's 401 keeps its v0.11 fields (error: "authentication_error", message) and adds code and status.

Retry-After. Every 503 carries Retry-After in seconds (never 0): the server's own estimate where it has one (5 s while starting, the memory budget's wait for media jobs, 30 s for a refused image-indexing page, the time to the scheduled end, else 60 s, in maintenance mode), else 5 s. A 429 carries the time to the window's reset. 408, 413, 501 and 504 carry none.

New to Dakera? Start with the Quickstart. For how retrieval, decay and the knowledge graph fit together, see How memory works.