Search Documentation
Search across all documentation pages
Agent Routes
All agent routes are POST endpoints under /api/agent/* (except GET /api/agent/info). Every request requires a valid agent key in the Authorization header. See Authentication for details.
Session & Context#
POST /api/agent/session-start#
Initializes a session and returns contextual data: recent episodic memories, important facts, active tasks, constraints, vault listing, active agents, documents, and pending messages.
Scope: read
Body:
| Field | Type | Default | Description |
|---|---|---|---|
vaultId | UUID | integration default | Target vault |
query | string | -- | Optional query for semantic search within context |
summaryOnly | boolean | true | Return clipped summaries instead of full content (saves tokens) |
mode | string | "default" | Context profile: default, planning, incident, handoff, deep, minimal, none |
maxEpisodic | int (0-10) | profile default | Override max episodic memories |
maxFacts | int (0-20) | profile default | Override max facts |
maxTasks | int (0-10) | profile default | Override max tasks |
maxConstraints | int (0-20) | profile default | Override max constraints |
includeDocuments | string[] | ["soul"] | Which documents to include: soul, instructions, skills, checks |
maxResponseChars | int (2000-100000) | 16000 | Budget cap for response size |
Response: Session context object with sessionContext, vaults, recentAgents, documents, pendingMessages, changesSinceLastSession, etc.
POST /api/agent/context-checkpoint#
Bulk-saves memories at session end with deduplication, plus an episodic session summary.
Scope: write
Body:
| Field | Type | Default | Description |
|---|---|---|---|
memories | array (max 50) | required | Array of memory objects to save |
sessionSummary | string | required | Session summary (saved as episodic memory) |
vaultId | UUID | -- | Target vault |
agentId | string | -- | Agent identifier |
modelId | string | -- | Model identifier |
agentRunId | string | -- | Run/session identifier (enables idempotency) |
dedup | boolean | true | Enable multi-layer deduplication |
Each memory in the array accepts: content, memoryType, summary, importance, confidence, entities, writeReason, relatedMemoryIds, sourceNoteIds, supersededById, metadata.
Response: { total, created, skipped, failed, durationMs, results[], pendingMessages? }
POST /api/agent/session-track#
Tracks session activity for a running agent session.
Scope: write
POST /api/agent/ingest-turn#
Captures a conversation turn with signal detection for extraction.
Scope: write
Body:
| Field | Type | Default | Description |
|---|---|---|---|
content | string (1-50000) | required | Turn content |
role | "user" | "assistant" | required | Who produced this turn |
vaultId | UUID | -- | Target vault |
agentId | string | -- | Agent identifier |
agentRunId | string | -- | Run identifier |
signalThreshold | int (0-10) | -- | Custom signal detection threshold |
customSignalKeywords | string[] | -- | Additional keywords for signal detection |
Response: { turnId, signalScore, signalKeywords, extractionStatus }
Memory Operations#
POST /api/agent/write-memory#
Writes a single memory with optional deduplication, encryption, and knowledge graph linking.
Scope: write
Body:
| Field | Type | Default | Description |
|---|---|---|---|
content | string (1-100000) | required | Memory content |
summary | string (max 2000) | -- | Short summary for token-efficient retrieval |
memoryType | string | "fact" | Type: fact, skill, preference, constraint, task, episodic, correction |
importance | int (1-5) | 3 | How important this memory is |
confidence | int (1-5) | 3 | How confident the agent is |
entities | string[] | -- | Extracted entities for filtering |
dedup | boolean | false | Enable 3-layer deduplication |
vaultId | UUID | -- | Target vault |
relatedMemoryIds | array | -- | Related memories with relation types |
sourceNoteIds | UUID[] | -- | Notes this memory was derived from |
supersededById | UUID | -- | Memory this supersedes |
externalWriteId | string | -- | Idempotency key |
expiresAt | datetime | -- | Auto-expiration timestamp |
metadata | object | -- | Arbitrary metadata |
writeReason | string | -- | Why this memory was written |
Response: { memoryId, created, idempotent, memoryType, vaultId, dedupAction?, supersededMemoryId? }
POST /api/agent/search-memories#
3-signal hybrid search: vector similarity + blind index + knowledge graph expansion, fused with Reciprocal Rank Fusion (RRF).
Scope: read, search
Body:
| Field | Type | Default | Description |
|---|---|---|---|
query | string (1-10000) | required | Search query |
topK | int (1-50) | 10 | Number of results |
threshold | float (0-1) | 0.4 | Minimum similarity score |
vaultId | UUID | -- | Scope to vault |
memoryType | string | -- | Filter by memory type |
includeArchived | boolean | false | Include archived memories |
decayHalfLife | int (1-365) | 30 | Temporal decay half-life in days |
diversity | float (0-1) | 0.7 | MMR diversity parameter |
Response: { searchMode, memories[], unitsUsed, embeddingTokens, semanticMatchCount, blindIndexMatchCount, graphExpansionCount }
POST /api/agent/read-memories#
Reads full content of specific memories by ID.
Scope: read
POST /api/agent/get-related-memories#
Retrieves memories related to a given memory via the knowledge graph.
Scope: read
POST /api/agent/update-memory#
Updates an existing memory's content, metadata, or importance.
Scope: write
POST /api/agent/archive-memory#
Archives a memory (soft delete). Archived memories are excluded from search by default.
Scope: write
POST /api/agent/cleanup-memories#
Bulk cleanup of old or low-importance memories.
Scope: write
Task Management#
POST /api/agent/create-task#
Creates a task (stored as a task-type memory) with status tracking and assignment.
Scope: write
Body:
| Field | Type | Default | Description |
|---|---|---|---|
title | string (1-10000) | required | Task title |
description | string (max 100000) | -- | Detailed description |
status | string | "todo" | Status: backlog, todo, in_progress, done, blocked |
priority | int (1-5) | 3 | Task priority (maps to importance) |
assignedAgentId | string | -- | Agent to assign the task to |
doneWhen | string | -- | Completion criteria |
vaultId | UUID | -- | Target vault |
dedup | boolean | false | Enable deduplication |
externalWriteId | string | -- | Idempotency key |
Response: { taskId, created, status, vaultId, dedupAction?, supersededTaskId? }
POST /api/agent/update-task#
Updates a task's status, priority, or metadata.
Scope: write
POST /api/agent/list-tasks#
Lists tasks with filtering by status and assignment.
Scope: read
Notes#
POST /api/agent/create-note#
Creates an encrypted note with optional folder placement.
Scope: write
POST /api/agent/read-note#
Reads a single note by ID with decrypted content.
Scope: read
POST /api/agent/read-notes#
Reads multiple notes by ID in a single request.
Scope: read
POST /api/agent/update-note#
Updates a note's title, content, or tags.
Scope: write
POST /api/agent/delete-note#
Soft-deletes (trashes) a note.
Scope: write
POST /api/agent/move-note#
Moves a note to a different folder.
Scope: write
POST /api/agent/search-notes#
Searches notes by title, tags, or content.
Scope: read, search
POST /api/agent/list-notes#
Lists notes in a vault or folder.
Scope: read
POST /api/agent/semantic-search#
Vector-based semantic search across notes using embeddings.
Scope: read, search
Body:
| Field | Type | Default | Description |
|---|---|---|---|
query | string (1-10000) | required | Search query |
topK | int (1-50) | 10 | Number of results |
threshold | float (0-1) | 0.5 | Minimum similarity |
vaultId | UUID | -- | Scope to vault |
Response: { notes[], embeddingTokens }
POST /api/agent/search-and-read#
Combined search and read in a single request -- searches notes, then returns full decrypted content of top matches.
Scope: read, search
Knowledge Graph#
POST /api/agent/add-link#
Creates a typed link between two nodes (memories or notes).
Scope: write
Body:
| Field | Type | Description |
|---|---|---|
sourceType | "note" | "memory" | Source node type |
sourceId | UUID | Source node ID |
targetType | "note" | "memory" | Target node type |
targetId | UUID | Target node ID |
relationType | string | Relation: wiki_link, derived_from, contradicts, refines, part_of, supersedes, source_of, references, manual |
label | string (max 500) | Optional encrypted label |
Response: { linkId, created, sourceType, sourceId, targetType, targetId, relationType }
POST /api/agent/remove-link#
Removes a knowledge graph link.
Scope: write
POST /api/agent/get-links#
Gets all links for a given node.
Scope: read
POST /api/agent/explore-graph#
Multi-hop graph traversal with optional semantic search entry points. Expands from seed nodes through knowledge graph relations.
Scope: read
Body:
| Field | Type | Default | Description |
|---|---|---|---|
query | string | -- | Semantic search to find entry points |
nodeId | UUID | -- | Start from a specific node |
nodeType | "note" | "memory" | -- | Type of the start node |
maxHops | int (1-5) | 2 | Maximum traversal depth |
maxNodes | int (1-200) | 50 | Maximum nodes to return |
vaultId | UUID | -- | Scope to vault |
Response: { entryPoints[], nodes[], edges[], stats: { totalNodes, totalEdges, maxHopReached } }
Folders & Vaults#
POST /api/agent/create-folder#
Creates a folder for organizing notes.
Scope: write
POST /api/agent/list-folders#
Lists folders in a vault.
Scope: read
POST /api/agent/create-vault#
Creates a new vault.
Scope: write
POST /api/agent/list-vaults#
Lists all accessible vaults with note counts.
Scope: read
Agent Messaging#
POST /api/agent/send-message#
Sends an encrypted message to another agent, a user, or broadcasts to all agents.
Scope: write
Body:
| Field | Type | Default | Description |
|---|---|---|---|
targetId | string | required | Target: agent ID, "user", or "*" (broadcast) |
targetType | string | auto-derived | "agent", "user", or "broadcast" |
category | string | "info" | Category: directive, question, info, task, alert |
priority | int (1-5) | 3 | Message priority |
subject | string (max 200) | -- | Message subject line |
content | string (1-10240) | required | Message body |
vaultId | UUID | -- | Vault context |
expiresInDays | int (1-365) | 30 | Days until message expires |
template | string | -- | Template: task_assignment, status_update, alert, question |
parentMessageId | UUID | -- | Parent message for threading |
Response: { messageId, created, targetId, targetType, category }
POST /api/agent/read-messages#
Reads messages received by this agent.
Scope: read
POST /api/agent/pending-messages#
Fetches unread pending messages.
Scope: read
POST /api/agent/ack-message#
Acknowledges receipt of a message.
Scope: write
POST /api/agent/list-active-agents#
Lists recently active agents in the vault.
Scope: read
Documents & Settings#
POST /api/agent/read-document#
Reads a vault document (soul, instructions, skills, or checks).
Scope: read
Body:
| Field | Type | Description |
|---|---|---|
documentType | string | One of: soul, instructions, skills, checks |
vaultId | UUID | Target vault (required) |
Response: { documentType, content, inheritMode, agentEditable, appendOnly, templateVersion }
POST /api/agent/update-document#
Updates a vault document (if agentEditable is true).
Scope: write
POST /api/agent/get-settings#
Gets vault settings.
Scope: read
POST /api/agent/update-settings#
Updates vault settings.
Scope: admin
Utility#
GET /api/agent/info#
Returns the current agent key's permissions and vault access (the only GET route).
Scope: none (any valid key)
Related Pages#
- API Overview -- Base URL, request/response format
- Authentication -- Agent keys and scopes
- Dashboard Routes -- Routes used by the web UI
- Error Handling -- Error codes and retry logic
- MCP Tools -- The same operations exposed as MCP tools