Suprflo REST API

Base URL: https://api.suprflo.com · Auth: Authorization: Bearer <API_KEY> · JSON.

All memory endpoints are under /api/memories. The API key determines the organization/project scope; within that you address memories by subject (user_id, agent_id, run_id, app_id).

---

Add memories

POST /api/memories

Extracts and stores durable facts from one or more messages.

{
  "messages": ["I'm vegetarian and allergic to peanuts"],
  "user_id": "alice",
  "agent_id": null,
  "run_id": null,
  "app_id": null,
  "metadata": { "source": "onboarding" },
  "infer": true,
  "async_mode": false,
  "timestamp": null
}

• messages — a list of strings, or a list of { "role": "user"|"assistant", "content": "..." } objects. The SDKs also accept a bare string, but the raw API requires an array.
• infer (default true) — extract facts. Set false to store the raw message verbatim.
• async_mode (default false) — return 202 immediately and extract in the background.

Response 200:

{ "results": [ { "id": "…", "memory": "Is vegetarian", "event": "ADD" }, … ] }

Search memories

POST /api/memories/search

{ "query": "what can this user eat?", "top_k": 10,
  "filters": { "user_id": "alice" }, "rerank": false, "memory_types": null }

Scope the search by putting user_id (and any of agent_id/run_id/app_id) inside filters. A top-level user_id on search is ignored, so it would search the whole tenant. Response 200:

{ "results": [ { "id": "…", "memory": "Is vegetarian", "score": 0.82, "metadata": {} }, … ] }

List memories

GET /api/memories?user_id=alice&limit=100&offset=0

Query params: user_id, agent_id, run_id, app_id, limit (1–1000, default 100), offset, as_of (ISO timestamp), memory_types (comma-separated).

Response: { "results": [ … ] }.

Get / update / delete a memory

• GET /api/memories/{id} → the memory object.
• PUT /api/memories/{id} — body { "data": "new text" } → updated memory.
• DELETE /api/memories/{id} → { "message": "…" }.

Delete all (scoped)

DELETE /api/memories — body { "user_id": "alice" } (or agent_id/run_id/app_id). Deletes every memory in that subject scope.

History

GET /api/memories/{id}/history → { "results": [ { "event": "ADD"|"UPDATE"|"DELETE", "old_memory": …, "new_memory": …, "created_at": … } ] }.

Subjects, export, config

• GET /api/memories/users — the memory subjects (users/agents) that have memories.
• GET /api/memories/export / POST /api/memories/import — bulk export/import.
• GET /api/memories/config — the effective retrieval/extraction config (handy for a health/credential check).

Errors

• 400 — invalid request ({ "detail": "…" }).
• 401/403 — missing/invalid key, or out-of-scope.
• 503 — upstream LLM/embedding backend temporarily unavailable (retryable).