Memory & Secrets API
Key-value and HMA-scoped agent memory, secrets, and workflow checkpoint endpoints.
Secrets
Per-Workspace Secrets
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /workspaces/:id/secrets | WorkspaceAuth | List secret keys for a workspace (keys only, values masked). |
| POST | /workspaces/:id/secrets | WorkspaceAuth | Set a secret { "key": "...", "value": "..." }. Auto-restarts the workspace. |
| PUT | /workspaces/:id/secrets | WorkspaceAuth | Alias for POST (upsert semantics). Auto-restarts the workspace. |
| DELETE | /workspaces/:id/secrets/:key | WorkspaceAuth | Delete a secret by key. Auto-restarts the workspace. |
| GET | /workspaces/:id/model | WorkspaceAuth | Return the model configuration derived from available API keys (which provider keys are set). |
Global Secrets
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /settings/secrets | AdminAuth | List global secrets (keys only, values masked). |
| PUT | /settings/secrets | AdminAuth | Set a global secret { "key": "...", "value": "..." }. Auto-restarts every non-paused/non-removed workspace that does not shadow the key with a workspace-level override. |
| POST | /settings/secrets | AdminAuth | Alias for PUT. |
| DELETE | /settings/secrets/:key | AdminAuth | Delete a global secret. Same auto-restart fan-out as PUT. |
Legacy aliases GET/POST/DELETE /admin/secrets[/:key] also exist and behave identically.
Memory
Key-Value Memory
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /workspaces/:id/memory | WorkspaceAuth | List all key-value memory entries for a workspace. |
| POST | /workspaces/:id/memory | WorkspaceAuth | Set a memory entry { "key": "...", "value": "..." }. |
| DELETE | /workspaces/:id/memory/:key | WorkspaceAuth | Delete a memory entry by key. |
Agent Memories (HMA-scoped)
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /workspaces/:id/memories | WorkspaceAuth | List or search agent memories. Supports ?q= for semantic search (see below). |
| POST | /workspaces/:id/memories | WorkspaceAuth | Create an agent memory entry. |
| GET | /workspaces/:id/v2/namespaces | WorkspaceAuth | List the HMA memory namespaces visible to this workspace (LOCAL / TEAM / GLOBAL scopes resolved along the org hierarchy). |
| GET | /workspaces/:id/v2/memories | WorkspaceAuth | List agent memories via the v2 namespace-scoped API. |
| DELETE | /workspaces/:id/v2/memories/:memoryId | WorkspaceAuth | Delete an agent memory by its ID (v2 API). |
Semantic search (?q=)
When a platform-level embedding function is configured, passing ?q=<text>
on GET /workspaces/:id/memories triggers vector similarity search instead of
the default full-text / ILIKE path:
GET /workspaces/{id}/memories?q=authentication+flow&limit=10
Authorization: Bearer {token}Matching entries are returned ordered by cosine similarity (most similar
first). Each row includes an additional similarity_score field (0–1, higher
is closer):
[
{
"id": "mem_abc123",
"key": "auth-design",
"value": "We use short-lived JWTs issued by the platform and refreshed via /auth/token.",
"similarity_score": 0.91,
"created_at": "2026-04-10T14:22:00Z"
}
]Graceful fallback: if no embedding function is configured, or if the
embedding call fails for a given query, the platform falls back transparently
to the text-search path. The similarity_score field is absent in fallback
responses. You do not need to change client code to handle both modes.
Workflow Checkpoints
Step-level progress persistence for long-running Temporal workflows. Workspaces with runtime: langgraph (Temporal) automatically save a checkpoint after each of the three workflow stages (task_receive, llm_call, task_complete) and resume from the last completed stage on restart.
Automatic resume behavior (runtime: langgraph only)
When a Temporal workspace restarts mid-workflow, the runtime reads the highest-index checkpoint and sets resume_from_step accordingly. Already-completed stages are skipped — the agent picks up exactly where it left off without re-running earlier steps.
Checkpoint I/O is non-fatal: network errors are silently swallowed. A crashed or unreachable platform never prevents the agent from running.
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /workspaces/:id/checkpoints | WorkspaceAuth | Upsert a step checkpoint. Body: { "workflow_id": "...", "step_name": "task_receive|llm_call|task_complete", "step_index": 0, "payload": {...} }. Uses ON CONFLICT DO UPDATE — safe to call multiple times. |
| GET | /workspaces/:id/checkpoints/:wfid | WorkspaceAuth | Return all checkpoints for a workflow, ordered by step_index DESC. Returns 404 if no checkpoints exist for the workflow. |
| DELETE | /workspaces/:id/checkpoints/:wfid | WorkspaceAuth | Clear all checkpoints for a workflow. Called by the runtime on clean task completion. Returns 404 if none exist. |
Step names and indices:
| Step | step_index | Meaning |
|---|---|---|
task_receive | 0 | Task received from A2A message |
llm_call | 1 | LLM inference completed |
task_complete | 2 | Task result sent back to caller |