Skip to main content
API docs by Redocly

Hindsight HTTP API (0.9.2)

Download OpenAPI specification:Download

License: Apache 2.0

HTTP API for Hindsight

Monitoring

Health check endpoint

Readiness check: verifies the API can reach the database. Alias of /health/ready. Use /health/live for liveness probes — this one fails whenever the database is unreachable, which must gate traffic, not restart the process.

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Readiness probe

Returns 200 when the API can serve traffic (database reachable), 503 otherwise. Identical to /health, which stays supported as its alias.

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Liveness probe

Returns 200 whenever the process can serve a request. Performs no database access, so a slow or unreachable database never restarts the pod. Point livenessProbe here and readinessProbe at /health.

Responses

Response Schema: application/json
status
required
string (Status)

Always "alive" — reaching this handler is the check

Value: "alive"
version
required
string (Version)

Hindsight version this process is running

uptime_seconds
required
number (Uptime Seconds)

Seconds since the process started

Response samples

Content type
application/json
{
  • "status": "alive",
  • "uptime_seconds": 812.4,
  • "version": "0.4.0"
}

Get API version and feature flags

Returns API version information and enabled feature flags. Use this to check which capabilities are available in this deployment.

Responses

Response Schema: application/json
api_version
required
string (Api Version)

API version string

required
object (FeaturesInfo)

Enabled feature flags

Response samples

Content type
application/json
{
  • "api_version": "0.9.0",
  • "features": {
    }
}

Prometheus metrics endpoint

Exports metrics in Prometheus format for scraping

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Memory

Get memory graph data

Retrieve graph data for visualization, optionally filtered by type (world/experience/observation).

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Type (string) or Type (null) (Type)
limit
integer (Limit) >= 0
Default: 1000
Q (string) or Q (null) (Q)
Array of Tags (strings) or Tags (null) (Tags)
tags_match
string (Tags Match)
Default: "all_strict"
Document Id (string) or Document Id (null) (Document Id)
Chunk Id (string) or Chunk Id (null) (Chunk Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Nodes)
required
Array of objects (Edges)
required
Array of objects (Table Rows)
total_units
required
integer (Total Units)
limit
required
integer (Limit)

Response samples

Content type
application/json
{
  • "edges": [
    ],
  • "limit": 1000,
  • "nodes": [
    ],
  • "table_rows": [
    ],
  • "total_units": 2
}

List memory units

List memory units with pagination and optional full-text search. Supports filtering by type, source document, and linked entity ID. Results are sorted by most recent first (mentioned_at DESC, then created_at DESC).

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Type (string) or Type (null) (Type)
Q (string) or Q (null) (Q)
Consolidation State (string) or Consolidation State (null) (Consolidation State)
State (string) or State (null) (State)
Document Id (string) or Document Id (null) (Document Id)
Entity Id (string) or Entity Id (null) (Entity Id)
Array of Tags (strings) or Tags (null) (Tags)
tags_match
string (Tags Match)
Default: "any"
Enum: "any" "all" "any_strict" "all_strict" "exact"
limit
integer (Limit) >= 0
Default: 100
offset
integer (Offset) >= 0
Default: 0
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Items)
total
required
integer (Total)
limit
required
integer (Limit)
offset
required
integer (Offset)

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "limit": 100,
  • "offset": 0,
  • "total": 150
}

Dry-run fact extraction (preview, no persistence)

Preview what the retain step would extract from text WITHOUT changing the bank — no entity resolution, links, embeddings, or persistence. Returns the candidate facts and the LLM token usage. Every prompt-affecting setting (retain mission, extraction mode, chunk size, …) is overridable in the body to A/B a candidate config against the bank's current one. This is a read-only tool: nothing is stored.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
content
required
string (Content)

Text to extract facts from (e.g. a document or a single chunk).

context
string (Context)
Default: ""

Optional context about the content.

Timestamp (string) or Timestamp (null) (Timestamp)

Reference timestamp for resolving relative times (ISO 8601).

Agent Name (string) or Agent Name (null) (Agent Name)
Deprecated

Deprecated: describe the speaker in context instead. Narrator override (memory owner) primed in the prompt; still honored for backwards compatibility.

Strategy (string) or Strategy (null) (Strategy)

Name of a retain strategy to extract under (a key of the bank's retain_strategies). Omit it and the bank's retain_default_strategy applies, exactly as it does for a retain that names none.

Retain Mission (string) or Retain Mission (null) (Retain Mission)
Retain Extraction Mode (string) or Retain Extraction Mode (null) (Retain Extraction Mode)
Retain Custom Instructions (string) or Retain Custom Instructions (null) (Retain Custom Instructions)
Retain Extract Causal Links (boolean) or Retain Extract Causal Links (null) (Retain Extract Causal Links)
Retain Chunk Size (integer) or Retain Chunk Size (null) (Retain Chunk Size)
Array of Entity Labels (objects) or Entity Labels (null) (Entity Labels)

Controlled vocabulary for entity labels (overrides the bank's config for this call)

Entities Allow Free Form (boolean) or Entities Allow Free Form (null) (Entities Allow Free Form)
Llm Output Language (string) or Llm Output Language (null) (Llm Output Language)

Responses

Response Schema: application/json
Array of objects (Facts)

Candidate facts the retain step would extract.

Array of objects (Chunks)

The chunks the input was cut into before extraction. Already computed on every path; returned because retain_chunk_size is otherwise a number with no visible effect.

object (TokenUsage)

Aggregated token usage across the extraction LLM calls.

Request samples

Content type
application/json
{
  • "content": "string",
  • "context": "",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "agent_name": "string",
  • "strategy": "string",
  • "retain_mission": "string",
  • "retain_extraction_mode": "string",
  • "retain_custom_instructions": "string",
  • "retain_extract_causal_links": true,
  • "retain_chunk_size": 0,
  • "entity_labels": [
    ],
  • "entities_allow_free_form": true,
  • "llm_output_language": "string"
}

Response samples

Content type
application/json
{
  • "facts": [
    ],
  • "chunks": [
    ],
  • "usage": {
    }
}

Get memory unit

Get a single memory unit by ID with all its metadata including entities and tags. Note: the 'history' field is deprecated and always returns an empty list - use GET /memories/{memory_id}/history instead.

path Parameters
bank_id
required
string (Bank Id)
memory_id
required
string (Memory Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Curate memory unit

Edit a memory's text and/or change its curation state (invalidate / revert). Invalidated memories are excluded from recall, consolidation, and graph maintenance but kept for audit (reversible). Only world/experience facts can be curated; observations are derived.

path Parameters
bank_id
required
string (Bank Id)
memory_id
required
string (Memory Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Text (string) or Text (null) (Text)

New fact text. Re-embeds the memory, drops its derived observations and links, and triggers re-consolidation.

Context (string) or Context (null) (Context)

New context for the fact. '' clears it; omit to leave unchanged.

Occurred Start (string) or Occurred Start (null) (Occurred Start)

New occurred-range start (ISO 8601). '' clears it; omit to leave unchanged.

Occurred End (string) or Occurred End (null) (Occurred End)

New occurred-range end (ISO 8601). '' clears it; omit to leave unchanged.

Fact Type (string) or Fact Type (null) (Fact Type)

Reclassify the fact: 'world' or 'experience'. Omit to leave unchanged.

Array of Entities (strings) or Entities (null) (Entities)

Replace the fact's entities. How each name is matched to an entity is governed by 'resolve_entities'. '[]' detaches all entities. Omit to leave unchanged.

resolve_entities
boolean (Resolve Entities)
Default: true

Whether the names in 'entities' are resolved against the entities already in the bank. True (default) is what retain does: a similar existing entity is reused when it scores above the match threshold, so a name close to one already in the bank may resolve to that one instead of the one you wrote. False takes the names literally — an existing entity is reused only on a case-insensitive name match, any other name creates a new entity, and names in the same request are never merged with each other. Use False for hand-authored corrections, where the name you sent is the answer rather than a guess. Ignored when 'entities' is omitted.

State (string) or State (null) (State)

Curation state: 'invalidated' to soft-retire the memory (excluded from recall/consolidation, links and derived observations pruned, moved to the archive) or 'valid' to revert. Reversible.

Reason (string) or Reason (null) (Reason)

Optional free-text reason recorded when invalidating.

Responses

Response Schema: application/json
any

Request samples

Content type
application/json
{
  • "reason": "superseded: server decommissioned 2026-06-01",
  • "state": "invalidated"
}

Response samples

Content type
application/json
null

Get observation history

Get the full history of an observation, with each change's source facts resolved to their text.

path Parameters
bank_id
required
string (Bank Id)
memory_id
required
string (Memory Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Recall memory

Recall memory using semantic similarity and spreading activation.

The types parameter is optional and may contain any of:

  • world: General knowledge about people, places, events, and things that happen
  • experience: Memories about experience, conversations, actions taken, and tasks performed
  • observation: Consolidated knowledge synthesized from facts

If types is omitted, all fact types are recalled.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
query
required
string (Query)
Array of Types (strings) or Types (null) (Types)

List of fact types to recall: 'world', 'experience', 'observation'. Defaults to all fact types if not specified.

prefer_observations
boolean (Prefer Observations)
Default: false

When recalling raw facts ('world'/'experience') together with 'observation', drop any raw fact that an observation in the results was consolidated from, so the observation supersedes it and you don't get duplicate content. The freed slots are backfilled with the next results, keeping the result count at the requested budget. Disabled by default; set to true to enable. No effect unless 'observation' and at least one raw type are both requested.

budget
string (Budget)
Default: "mid"
Enum: "low" "mid" "high"

Budget levels for recall/reflect operations.

max_tokens
integer (Max Tokens)
Default: 4096
trace
boolean (Trace)
Default: false
Query Timestamp (string) or Query Timestamp (null) (Query Timestamp)

ISO format date string (e.g., '2023-05-30T23:40:00'). Used as the query-time anchor for relative temporal expressions and recency scoring.

object (IncludeOptions)
Default: {}

Options for including additional data (entities are included by default)

Array of Tags (strings) or Tags (null) (Tags)

Filter memories by tags. If not specified, all memories are returned. Omitting tags (or passing []) together with tags_match='exact' filters to untagged/global observations only (the scope written by observation_scopes='shared').

tags_match
string (Tags Match)
Default: "any"
Enum: "any" "all" "any_strict" "all_strict" "exact"

How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged), 'exact' (set-equality on the full scope, excludes untagged). With 'exact' and no tags (or []), the empty global scope is selected and only untagged memories match.

(Array of Tag Groups (TagGroupLeaf (object) or TagGroupAnd (object) or TagGroupOr (object) or TagGroupNot (object))) or Tag Groups (null) (Tag Groups)

Compound tag filter using boolean groups. Groups in the list are AND-ed. Each group is a leaf {tags, match} or compound {and: [...]}, {or: [...]}, {not: ...}. A leaf may set resolve='fuzzy' to match its tags against the bank's tags by trigram similarity instead of literally, so a query that says 'typsecript' still reaches memories tagged 'typescript'.

MinScores (object) or null

Optional per-stage score floors, each inclusive (>=). semantic and keyword are retrieval-level cutoffs pushed into the SQL arm they name (overriding the global similarity/BM25 minimums for this request), and constrain only that arm: recall fuses four arms (semantic, keyword, graph, temporal) and returns a result surfaced by any of them, so a returned result reports null for a stage that did not surface it (a non-null score always clears its floor). Setting both therefore does not restrict the response to results clearing both. reranker and final are post-ranking filters applied to every scored result, so those floors are guaranteed by each result returned — use them for query abstention. Any field left unset imposes no floor; omitting min_scores entirely (the default) applies no score filtering. Use with care — the reranker's absolute scores are not calibrated across queries (a clearly-relevant match may score ~0.001 even though it is ranked first).

TemporalWindow (object) or null

Window for the temporal retrieval arm, supplied instead of extracting dates from query. Set this when you already know the range you mean — a date picker, or an agent that resolved 'last quarter' itself — and recall will skip parsing the query text for dates. This ranks, it does not filter: the temporal arm surfaces memories whose own dates (mentioned_at, occurred_start, occurred_end) fall inside the window so they rank higher, while the semantic, keyword and graph arms are unaffected — so memories dated outside the window are still returned. Ignored when the bank has temporal retrieval disabled.

Responses

Response Schema: application/json
required
Array of objects (Results)
Trace (object) or Trace (null) (Trace)
Entities (object) or Entities (null) (Entities)

Entity states for entities mentioned in results

Chunks (object) or Chunks (null) (Chunks)

Chunks for facts, keyed by chunk_id

Source Facts (object) or Source Facts (null) (Source Facts)

Source facts for observation-type results, keyed by fact ID

Source Facts Truncated (boolean) or Source Facts Truncated (null) (Source Facts Truncated)

Whether the source_facts map was cut short by the token budget. When true, some IDs in results[].source_fact_ids have no entry in source_facts — the budget ran out, the references are not dangling. Only set when source facts were requested.

Request samples

Content type
application/json
{
  • "budget": "mid",
  • "include": {
    },
  • "max_tokens": 4096,
  • "query": "What did Alice say about machine learning?",
  • "query_timestamp": "2023-05-30T23:40:00",
  • "tags": [
    ],
  • "tags_match": "any",
  • "temporal_window": {
    },
  • "trace": true,
  • "types": [
    ]
}

Response samples

Content type
application/json
{
  • "chunks": {
    },
  • "entities": {
    },
  • "results": [
    ],
  • "trace": {
    }
}

Reflect and generate answer

Reflect and formulate an answer using bank identity, world facts, observations, and mental models.

This endpoint:

  1. Retrieves experience (conversations and events)
  2. Retrieves world facts relevant to the query
  3. Retrieves observations and mental models (bank's synthesized perspectives)
  4. Uses LLM to formulate a contextual answer
  5. Returns plain text answer and the facts used
path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
query
required
string (Query)
budget
string (Budget)
Default: "low"
Enum: "low" "mid" "high"

Budget levels for recall/reflect operations.

Context (string) or Context (null) (Context)
Deprecated

DEPRECATED: Additional context is now concatenated with the query. Pass context directly in the query field instead. If provided, it will be appended to the query for backward compatibility.

max_tokens
integer (Max Tokens)
Default: 4096

Maximum tokens for the response

object (ReflectIncludeOptions)

Options for including additional data (disabled by default)

Response Schema (object) or Response Schema (null) (Response Schema)

Optional JSON Schema for structured output. When provided, the response will include a 'structured_output' field with the LLM response parsed according to this schema.

Array of Tags (strings) or Tags (null) (Tags)

Scope raw facts, observations, mental models, and tagged directives during reflection. With no tags, memory retrieval is unfiltered while only untagged/global directives are loaded. Use tags=[] with tags_match='exact' to select the untagged/global scope.

tags_match
string (Tags Match)
Default: "any"
Enum: "any" "all" "any_strict" "all_strict" "exact"

How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged), or 'exact' (set equality). Untagged directives remain global in every mode.

(Array of Tag Groups (TagGroupLeaf (object) or TagGroupAnd (object) or TagGroupOr (object) or TagGroupNot (object))) or Tag Groups (null) (Tag Groups)

Compound tag filter using boolean groups. Groups in the list are AND-ed. Each group is a leaf {tags, match} or compound {and: [...]}, {or: [...]}, {not: ...}. Mutually exclusive with tags. A leaf may set resolve='fuzzy' to match its tags against the bank's tags by trigram similarity instead of literally, so a query that says 'typsecript' still reaches memories tagged 'typescript'.

apply_all_directives
boolean (Apply All Directives)
Default: false

Apply every active directive regardless of tags. By default directives are scoped like memories: untagged directives always apply, and tagged directives apply only when the request's tags match them. Set true to apply all active directives, ignoring tag scope.

Array of Fact Types (strings) or Fact Types (null) (Fact Types)

Filter which fact types are retrieved during reflect. None means all types (world, experience, observation).

exclude_mental_models
boolean (Exclude Mental Models)
Default: false

If true, exclude all mental models from the reflect loop (skip search_mental_models tool).

Array of Exclude Mental Model Ids (strings) or Exclude Mental Model Ids (null) (Exclude Mental Model Ids)

Exclude specific mental models by ID from the reflect loop.

Responses

Response Schema: application/json
text
required
string (Text)

The reflect response as well-formatted markdown (headers, lists, bold/italic, code blocks, etc.)

ReflectBasedOn (object) or null

Evidence used to generate the response. Only present when include.facts is set.

Structured Output (object) or Structured Output (null) (Structured Output)

Structured output parsed according to the request's response_schema. Only present when response_schema was provided in the request.

Structured Output Error (string) or Structured Output Error (null) (Structured Output Error)

Why structured output could not be produced. Present only when a response_schema was given and the extraction call failed (provider error, timeout, unparseable output). A missing structured_output without this field means the answer held nothing matching the schema — the reflect itself still succeeded either way.

TokenUsage (object) or null

Token usage metrics for LLM calls during reflection.

ReflectTrace (object) or null

Execution trace of tool and LLM calls. Only present when include.tool_calls is set.

Request samples

Content type
application/json
{
  • "budget": "low",
  • "include": {
    },
  • "max_tokens": 4096,
  • "query": "What do you think about artificial intelligence?",
  • "response_schema": {
    },
  • "tags": [
    ],
  • "tags_match": "any"
}

Response samples

Content type
application/json
{
  • "based_on": {
    },
  • "structured_output": {
    },
  • "text": "## AI Overview\n\nBased on my understanding, AI is a **transformative technology**:\n\n- Used extensively in healthcare\n- Discussed in recent conversations\n- Continues to evolve rapidly",
  • "trace": {
    },
  • "usage": {
    }
}

List tags

List all unique tags in a memory bank with usage counts. Supports wildcard search using '' (e.g., 'user:', '-fred', 'tag-2'). Case-insensitive. Use source=mental_models to list tags used on mental models instead of memories.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Q (string) or Q (null) (Q)

Wildcard pattern to filter tags (e.g., 'user:' for user:alice, '-admin' for role-admin). Use '*' as wildcard. Case-insensitive.

source
string (Source)
Default: "memories"
Enum: "memories" "mental_models"

Where to read tags from: 'memories' (memory_units, default) or 'mental_models'.

limit
integer (Limit) >= 0
Default: 100

Maximum number of tags to return

offset
integer (Offset) >= 0
Default: 0

Offset for pagination

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Items)
total
required
integer (Total)
limit
required
integer (Limit)
offset
required
integer (Offset)

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "limit": 100,
  • "offset": 0,
  • "total": 25
}

Fetch an attachment retained inline with a document

Serve the bytes of an attachment retained as inline content. The id is the one inside a placeholder token, and is returned on attachments[].url by recall and by the document/chunk/memory reads — so an agent can show or reason over the original behind an attachment-derived fact.

Bytes are served with the Content-Type the caller declared at retain. Access is authorized against the bank; a missing attachment and an invisible bank both return 404, so the endpoint cannot be used to probe what a bank holds.

path Parameters
bank_id
required
string (Bank Id)
attachment_id
required
string (Attachment Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema:
any

Response samples

Content type
null

List observation scopes

Enumerate the distinct scopes across a bank's observations. Each observation lives under a scope: the exact set of tags it was consolidated with. Returns every distinct scope (tag order normalized) with the number of observations in it; the empty tag list is the global/untagged scope. Use a returned scope with the graph endpoint (tags= & tags_match=exact) to filter observations to exactly that scope. Paged: total reports every distinct scope in the bank.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
limit
integer (Limit) [ 0 .. 1000 ]
Default: 100

Maximum number of scopes to return

offset
integer (Offset) >= 0
Default: 0

Offset for pagination

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Scopes)

Distinct observation scopes, most populous first

total
required
integer (Total)

Total number of distinct scopes in the bank (ignores limit/offset)

limit
required
integer (Limit)

Maximum number of scopes returned in this page

offset
required
integer (Offset)

Offset this page started at

Response samples

Content type
application/json
{
  • "limit": 100,
  • "offset": 0,
  • "scopes": [
    ],
  • "total": 3
}

Clear observations for a memory

Delete all observations derived from a specific memory and reset it for re-consolidation. The memory itself is not deleted. A consolidation job is triggered automatically so the memory will produce fresh observations on the next consolidation run.

path Parameters
bank_id
required
string (Bank Id)
memory_id
required
string (Memory Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
deleted_count
required
integer (Deleted Count)

Response samples

Content type
application/json
{
  • "deleted_count": 3
}

Retain memories

Retain memory items with automatic fact extraction.

This is the main endpoint for storing memories. It supports both synchronous and asynchronous processing via the async parameter.

Features:

  • Efficient batch processing
  • Automatic fact extraction from natural language
  • Entity recognition and linking
  • Document tracking with automatic upsert (when document_id is provided)
  • Temporal and semantic linking
  • Optional asynchronous processing

The system automatically:

  1. Extracts semantic facts from the content
  2. Generates embeddings
  3. Deduplicates similar facts
  4. Creates temporal, semantic, and entity links
  5. Tracks document metadata

When async=true: Returns immediately after queuing. Use the operations endpoint to monitor progress.

When async=false (default): Waits for processing to complete.

Note: If a memory item has a document_id that already exists, the old document and its memory units will be deleted before creating new ones (upsert behavior).

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
required
Array of objects (Items)
async
boolean (Async)
Default: false

If true, process asynchronously in background. If false, wait for completion (default: false)

Array of Document Tags (strings) or Document Tags (null) (Document Tags)
Deprecated

Deprecated. Use item-level tags instead.

Operation Id (string) or Operation Id (null) (Operation Id)

Optional client-supplied UUID used as the identity of an async retain operation. Re-submitting with the same operation_id returns the original operation and creates no new work, so retrying after a lost or timed-out acknowledgement will not enqueue a duplicate. Reusing an id that belongs to a different operation returns HTTP 409. Ignored for synchronous retain.

Responses

Response Schema: application/json
success
required
boolean (Success)
bank_id
required
string (Bank Id)
items_count
required
integer (Items Count)
async
required
boolean (Async)

Whether the operation was processed asynchronously

Operation Id (string) or Operation Id (null) (Operation Id)

Operation ID for tracking async operations. Use GET /v1/default/banks/{bank_id}/operations to list operations. Only present when async=true. When items use different per-item strategies, use operation_ids instead.

Array of Operation Ids (strings) or Operation Ids (null) (Operation Ids)

Operation IDs when items were submitted as multiple strategy groups (async=true with mixed per-item strategies). operation_id is set to the first entry for backward compatibility.

TokenUsage (object) or null

Token usage metrics for LLM calls during fact extraction (only present for synchronous operations)

Request samples

Content type
application/json
{
  • "async": false,
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "async": false,
  • "bank_id": "user123",
  • "items_count": 2,
  • "success": true,
  • "usage": {
    }
}

Clear memory bank memories

Delete memory units for a memory bank. Optionally filter by type (world, experience, observation) to delete only specific types. This is a destructive operation that cannot be undone. The bank profile (disposition and background) will be preserved.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Type (string) or Type (null) (Type)

Optional fact type filter (world, experience, observation)

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
success
required
boolean (Success)
Message (string) or Message (null) (Message)
Deleted Count (integer) or Deleted Count (null) (Deleted Count)

Response samples

Content type
application/json
{
  • "deleted_count": 10,
  • "message": "Deleted successfully",
  • "success": true
}

Banks

Preview an operation's prompts (no LLM call)

Render the exact system and user messages retain, consolidation or reflect would send for this bank, without calling an LLM, reading memories, or changing anything. Everything that shapes the prompt comes from the bank; the runtime data an operation would be given is a fixed placeholder. Both messages are returned: retain and consolidation keep their system prompt bank-agnostic (one provider-side cache serves every bank) and carry the mission in the user message instead.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
operation
string (Operation)
Default: "retain"
Enum: "retain" "consolidation" "reflect"

Which operation's prompts to render.

Strategy (string) or Strategy (null) (Strategy)

Name of a retain strategy to render under (a key of the bank's retain_strategies). Retain only. Omit it and the bank's retain_default_strategy applies, exactly as it does for a retain that names none.

Responses

Response Schema: application/json
Array of objects (Messages)

Request messages, in send order. Each is given as the blocks it is built from.

Strategy (string) or Strategy (null) (Strategy)

The retain strategy these prompts were rendered under, if any.

strategies
Array of strings (Strategies)

Names of the bank's retain strategies, so a client can offer them without a second call.

Array of objects (Run Settings)

Settings that shape the operation without appearing in its prompt, such as chunk sizes.

Response Schema (object) or Response Schema (null) (Response Schema)

JSON schema the response is constrained to, when the operation constrains it.

Skipped Reason (string) or Skipped Reason (null) (Skipped Reason)

Why no prompt is sent, when the configuration means none is.

Request samples

Content type
application/json
{
  • "operation": "retain"
}

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "strategy": "string",
  • "strategies": [
    ],
  • "run_settings": [
    ],
  • "response_schema": { },
  • "skipped_reason": "string"
}

List memory banks

List banks with their profiles and summary stats, most recently written first (last_write_at descending), with pagination and optional search.

query Parameters
Q (string) or Q (null) (Q)

Case-insensitive substring filter on bank ID or name (e.g. 'alice')

limit
integer (Limit) >= 0
Default: 100

Maximum number of banks to return

offset
integer (Offset) >= 0
Default: 0

Offset for pagination

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Banks)
total
required
integer (Total)

Total number of banks visible to the caller, ignoring limit/offset.

limit
required
integer (Limit)
offset
required
integer (Offset)

Response samples

Content type
application/json
{
  • "banks": [
    ],
  • "limit": 100,
  • "offset": 0,
  • "total": 50
}

Get statistics for memory bank

Get statistics about nodes and links for a specific agent

path Parameters
bank_id
required
string (Bank Id)
query Parameters
refresh
boolean (Refresh)
Default: false

Force a fresh recompute, bypassing the cached value (and refreshing the cache).

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
total_nodes
required
integer (Total Nodes)
total_links
required
integer (Total Links)
total_documents
required
integer (Total Documents)
required
object (Nodes By Fact Type)
required
object (Links By Link Type)
required
object (Links By Fact Type)
required
object (Links Breakdown)
pending_operations
required
integer (Pending Operations)
failed_operations
required
integer (Failed Operations)
object (Operations By Status)

Async operations grouped by status (pending, processing, completed, failed, cancelled).

Last Consolidated At (string) or Last Consolidated At (null) (Last Consolidated At)

When consolidation last ran (ISO format)

Last Memory Write At (string) or Last Memory Write At (null) (Last Memory Write At)

When a memory was last written in this bank — stored, edited, or consolidated (ISO format). Null if the bank has no memories. A mental model whose last_memory_seen_at is at or after this is up to date whatever its tags; an older one may need a refresh, which only the single mental-model read can confirm.

pending_consolidation
integer (Pending Consolidation)
Default: 0

Number of source memories (world/experience) still queued for consolidation into observations. Excludes memories whose consolidation permanently failed — those are counted only in failed_consolidation — so this drains to 0 when the consolidator catches up.

failed_consolidation
integer (Failed Consolidation)
Default: 0

Number of source memories (world/experience) whose consolidation permanently failed and can be retried via the consolidation recovery endpoint.

total_observations
integer (Total Observations)
Default: 0

Total number of observations

Response samples

Content type
application/json
{
  • "bank_id": "user123",
  • "failed_consolidation": 0,
  • "failed_operations": 0,
  • "last_consolidated_at": "2024-01-15T10:30:00Z",
  • "last_memory_write_at": "2024-01-15T11:05:00Z",
  • "links_breakdown": {
    },
  • "links_by_fact_type": {
    },
  • "links_by_link_type": {
    },
  • "nodes_by_fact_type": {
    },
  • "pending_consolidation": 0,
  • "pending_operations": 2,
  • "total_documents": 10,
  • "total_links": 300,
  • "total_nodes": 150,
  • "total_observations": 45
}

Test the bank's LLM connectivity

Probe the LLMs this bank would use for retain / consolidation / reflect with one minimal call each (configs shared across operations are probed once), so you can discover 'not configured / unreachable' instead of a silent stall. Deliberate action (makes a real provider call); not for polling. Returns status only — never the provider, model, endpoint, API key, or raw error. Disable with HINDSIGHT_API_ENABLE_BANK_LLM_HEALTH=false.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)

Bank identifier

required
Array of objects (Operations)

Connectivity status per operation (retain, consolidation, reflect)

Response samples

Content type
application/json
{
  • "bank_id": "user123",
  • "operations": [
    ]
}

Memory ingestion time-series

Memories ingested over a period, bucketed by time and broken down by fact type.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
period
string (Period)
Default: "7d"
time_field
string (Time Field)
Default: "created_at"

Timestamp column to bucket on. created_at (default) = ingest time; mentioned_at / occurred_start = event time, useful for migrated corpora where ingest time is a single point and doesn't reflect the underlying knowledge timeline. Unknown values fall back to created_at.

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
period
required
string (Period)

One of: 1h, 12h, 1d, 7d, 30d, 90d.

trunc
required
string (Trunc)

Bucket granularity: minute, hour, day.

time_field
string (Time Field)
Default: "created_at"

Timestamp column used to assign each row to a bucket. created_at shows ingest time; mentioned_at / occurred_start show event time (falls back to created_at per row when null).

Array of objects (Buckets)

Per-bucket counts, always returned fully padded for the requested period.

Response samples

Content type
application/json
{
  • "bank_id": "string",
  • "period": "string",
  • "trunc": "string",
  • "time_field": "created_at",
  • "buckets": [
    ]
}

Get memory bank profile (removed — use GET .../config) Deprecated

Removed. The bank profile endpoints have been removed. Disposition traits and the reflect mission are bank configuration: read them from GET /v1/default/banks/{bank_id}/config as disposition_skepticism, disposition_literalism, disposition_empathy and reflect_mission, and write them with PATCH /v1/default/banks/{bank_id}/config. The name field this endpoint also returned was a display-only label; read it from GET /v1/default/banks.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
name
required
string (Name)
required
object (DispositionTraits)

Disposition traits that influence how memories are formed and interpreted.

mission
required
string (Mission)

The agent's mission - who they are and what they're trying to accomplish

Background (string) or Background (null) (Background)

Deprecated: use mission instead

Response samples

Content type
application/json
{
  • "bank_id": "user123",
  • "disposition": {
    },
  • "mission": "I am a software engineer helping my team stay organized and ship quality code",
  • "name": "Alice"
}

Update memory bank disposition (removed — use PATCH .../config) Deprecated

Removed. The bank profile endpoints have been removed. Disposition traits and the reflect mission are bank configuration: read them from GET /v1/default/banks/{bank_id}/config as disposition_skepticism, disposition_literalism, disposition_empathy and reflect_mission, and write them with PATCH /v1/default/banks/{bank_id}/config. The name field this endpoint also returned was a display-only label; read it from GET /v1/default/banks.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
required
object (DispositionTraits)

Disposition traits that influence how memories are formed and interpreted.

skepticism
required
integer (Skepticism) [ 1 .. 5 ]

How skeptical vs trusting (1=trusting, 5=skeptical)

literalism
required
integer (Literalism) [ 1 .. 5 ]

How literally to interpret information (1=flexible, 5=literal)

empathy
required
integer (Empathy) [ 1 .. 5 ]

How much to consider emotional context (1=detached, 5=empathetic)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
name
required
string (Name)
required
object (DispositionTraits)

Disposition traits that influence how memories are formed and interpreted.

mission
required
string (Mission)

The agent's mission - who they are and what they're trying to accomplish

Background (string) or Background (null) (Background)

Deprecated: use mission instead

Request samples

Content type
application/json
{
  • "disposition": {
    }
}

Response samples

Content type
application/json
{
  • "bank_id": "user123",
  • "disposition": {
    },
  • "mission": "I am a software engineer helping my team stay organized and ship quality code",
  • "name": "Alice"
}

Add/merge memory bank background (removed — use PATCH .../config) Deprecated

Removed. The bank background was folded into the reflect mission. Write it with PATCH /v1/default/banks/{bank_id}/config as reflect_mission. That call replaces the value rather than merging into it, so read the current mission from GET .../config first if you relied on this endpoint's append behaviour.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
content
required
string (Content)

New background information to add or merge

update_disposition
boolean (Update Disposition)
Default: true

Deprecated - disposition is no longer auto-inferred from mission

Responses

Response Schema: application/json
mission
required
string (Mission)
Background (string) or Background (null) (Background)

Deprecated: same as mission

DispositionTraits (object) or null

Request samples

Content type
application/json
{
  • "content": "I was born in Texas",
  • "update_disposition": true
}

Response samples

Content type
application/json
{
  • "mission": "I was born in Texas. I am a software engineer with 10 years of experience."
}

Create or update memory bank

Create a new agent or update existing agent with disposition and mission. Auto-fills missing fields with defaults.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)

Deprecated: display label only, not advertised

DispositionTraits (object) or null

Deprecated: use update_bank_config instead

Disposition Skepticism (integer) or Disposition Skepticism (null) (Disposition Skepticism)

Deprecated: use update_bank_config instead

Disposition Literalism (integer) or Disposition Literalism (null) (Disposition Literalism)

Deprecated: use update_bank_config instead

Disposition Empathy (integer) or Disposition Empathy (null) (Disposition Empathy)

Deprecated: use update_bank_config instead

Mission (string) or Mission (null) (Mission)

Deprecated: use update_bank_config with reflect_mission instead

Background (string) or Background (null) (Background)

Deprecated: use update_bank_config with reflect_mission instead

Reflect Mission (string) or Reflect Mission (null) (Reflect Mission)

Mission/context for Reflect operations. Guides how Reflect interprets and uses memories.

Retain Mission (string) or Retain Mission (null) (Retain Mission)

Steers what gets extracted during retain(). Injected alongside built-in extraction rules.

Retain Extraction Mode (string) or Retain Extraction Mode (null) (Retain Extraction Mode)

Fact extraction mode: 'concise' (default), 'verbose', 'custom', 'verbatim', or 'chunks'.

Retain Custom Instructions (string) or Retain Custom Instructions (null) (Retain Custom Instructions)

Custom extraction prompt. Only active when retain_extraction_mode is 'custom'.

Retain Chunk Size (integer) or Retain Chunk Size (null) (Retain Chunk Size)

Target maximum characters for each content chunk during retain.

Retain Structured Chunk Size (integer) or Retain Structured Chunk Size (null) (Retain Structured Chunk Size)

Maximum characters for a single JSONL line or conversation turn to keep whole during retain. Defaults to retain_chunk_size when unset.

Retain Max Attachments Per Chunk (integer) or Retain Max Attachments Per Chunk (null) (Retain Max Attachments Per Chunk)

Maximum inline attachments one extraction chunk may carry. retain_chunk_size budgets text only — a placeholder costs the characters it occupies and nothing more — so this is what bounds attachments. Match it to the provider's per-request limit.

Enable Observations (boolean) or Enable Observations (null) (Enable Observations)

Toggle automatic observation consolidation after retain().

Observations Mission (string) or Observations Mission (null) (Observations Mission)

Controls what gets synthesised into observations. Replaces built-in consolidation rules entirely.

Enable Text Search (boolean) or Enable Text Search (null) (Enable Text Search)

Toggle the keyword (BM25) retrieval arm during recall. Disabling leaves pure vector search: the arm is left out of the query entirely rather than filtered to nothing, so none of its cost is paid. Also drops the keyword arm from knowledge-page search.

Enable Temporal Retrieval (boolean) or Enable Temporal Retrieval (null) (Enable Temporal Retrieval)

Toggle the temporal retrieval arm during recall, together with the date-aware query analysis that feeds it. Useful for banks whose content carries no meaningful dates.

Enable Graph Retrieval (boolean) or Enable Graph Retrieval (null) (Enable Graph Retrieval)

Toggle the entity/link graph traversal arm during recall. Disabling trades relational recall for latency on banks whose content has little entity structure.

Enable Reranking (boolean) or Enable Reranking (null) (Enable Reranking)

Toggle cross-encoder reranking during recall. Disabling returns the RRF-fused ordering directly, which is faster but less precise.

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
name
required
string (Name)
required
object (DispositionTraits)

Disposition traits that influence how memories are formed and interpreted.

mission
required
string (Mission)

The agent's mission - who they are and what they're trying to accomplish

Background (string) or Background (null) (Background)

Deprecated: use mission instead

Request samples

Content type
application/json
{
  • "observations_mission": "Observations are stable facts about people and projects. Always include preferences and skills.",
  • "retain_mission": "Always include technical decisions and architectural trade-offs. Ignore meeting logistics."
}

Response samples

Content type
application/json
{
  • "bank_id": "user123",
  • "disposition": {
    },
  • "mission": "I am a software engineer helping my team stay organized and ship quality code",
  • "name": "Alice"
}

Partial update memory bank

Partially update an agent's profile. Only provided fields will be updated.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)

Deprecated: display label only, not advertised

DispositionTraits (object) or null

Deprecated: use update_bank_config instead

Disposition Skepticism (integer) or Disposition Skepticism (null) (Disposition Skepticism)

Deprecated: use update_bank_config instead

Disposition Literalism (integer) or Disposition Literalism (null) (Disposition Literalism)

Deprecated: use update_bank_config instead

Disposition Empathy (integer) or Disposition Empathy (null) (Disposition Empathy)

Deprecated: use update_bank_config instead

Mission (string) or Mission (null) (Mission)

Deprecated: use update_bank_config with reflect_mission instead

Background (string) or Background (null) (Background)

Deprecated: use update_bank_config with reflect_mission instead

Reflect Mission (string) or Reflect Mission (null) (Reflect Mission)

Mission/context for Reflect operations. Guides how Reflect interprets and uses memories.

Retain Mission (string) or Retain Mission (null) (Retain Mission)

Steers what gets extracted during retain(). Injected alongside built-in extraction rules.

Retain Extraction Mode (string) or Retain Extraction Mode (null) (Retain Extraction Mode)

Fact extraction mode: 'concise' (default), 'verbose', 'custom', 'verbatim', or 'chunks'.

Retain Custom Instructions (string) or Retain Custom Instructions (null) (Retain Custom Instructions)

Custom extraction prompt. Only active when retain_extraction_mode is 'custom'.

Retain Chunk Size (integer) or Retain Chunk Size (null) (Retain Chunk Size)

Target maximum characters for each content chunk during retain.

Retain Structured Chunk Size (integer) or Retain Structured Chunk Size (null) (Retain Structured Chunk Size)

Maximum characters for a single JSONL line or conversation turn to keep whole during retain. Defaults to retain_chunk_size when unset.

Retain Max Attachments Per Chunk (integer) or Retain Max Attachments Per Chunk (null) (Retain Max Attachments Per Chunk)

Maximum inline attachments one extraction chunk may carry. retain_chunk_size budgets text only — a placeholder costs the characters it occupies and nothing more — so this is what bounds attachments. Match it to the provider's per-request limit.

Enable Observations (boolean) or Enable Observations (null) (Enable Observations)

Toggle automatic observation consolidation after retain().

Observations Mission (string) or Observations Mission (null) (Observations Mission)

Controls what gets synthesised into observations. Replaces built-in consolidation rules entirely.

Enable Text Search (boolean) or Enable Text Search (null) (Enable Text Search)

Toggle the keyword (BM25) retrieval arm during recall. Disabling leaves pure vector search: the arm is left out of the query entirely rather than filtered to nothing, so none of its cost is paid. Also drops the keyword arm from knowledge-page search.

Enable Temporal Retrieval (boolean) or Enable Temporal Retrieval (null) (Enable Temporal Retrieval)

Toggle the temporal retrieval arm during recall, together with the date-aware query analysis that feeds it. Useful for banks whose content carries no meaningful dates.

Enable Graph Retrieval (boolean) or Enable Graph Retrieval (null) (Enable Graph Retrieval)

Toggle the entity/link graph traversal arm during recall. Disabling trades relational recall for latency on banks whose content has little entity structure.

Enable Reranking (boolean) or Enable Reranking (null) (Enable Reranking)

Toggle cross-encoder reranking during recall. Disabling returns the RRF-fused ordering directly, which is faster but less precise.

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
name
required
string (Name)
required
object (DispositionTraits)

Disposition traits that influence how memories are formed and interpreted.

mission
required
string (Mission)

The agent's mission - who they are and what they're trying to accomplish

Background (string) or Background (null) (Background)

Deprecated: use mission instead

Request samples

Content type
application/json
{
  • "observations_mission": "Observations are stable facts about people and projects. Always include preferences and skills.",
  • "retain_mission": "Always include technical decisions and architectural trade-offs. Ignore meeting logistics."
}

Response samples

Content type
application/json
{
  • "bank_id": "user123",
  • "disposition": {
    },
  • "mission": "I am a software engineer helping my team stay organized and ship quality code",
  • "name": "Alice"
}

Delete memory bank

Delete an entire memory bank including all memories, entities, documents, and the bank profile itself. This is a destructive operation that cannot be undone.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
success
required
boolean (Success)
Message (string) or Message (null) (Message)
Deleted Count (integer) or Deleted Count (null) (Deleted Count)

Response samples

Content type
application/json
{
  • "deleted_count": 10,
  • "message": "Deleted successfully",
  • "success": true
}

Clear all observations

Delete all observations for a memory bank. This is useful for resetting the consolidated knowledge.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
success
required
boolean (Success)
Message (string) or Message (null) (Message)
Deleted Count (integer) or Deleted Count (null) (Deleted Count)

Response samples

Content type
application/json
{
  • "deleted_count": 10,
  • "message": "Deleted successfully",
  • "success": true
}

Recover failed consolidation

Reset all memories that were permanently marked as failed during consolidation (after exhausting all LLM retries and adaptive batch splitting) so they are picked up again on the next consolidation run. Does not delete any observations.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
retried_count
required
integer (Retried Count)

Response samples

Content type
application/json
{
  • "retried_count": 42
}

Get bank configuration

Get fully resolved configuration for a bank including all hierarchical overrides (global → tenant → bank). The 'config' field contains all resolved config values. The 'overrides' field shows only bank-specific overrides. Always available: HINDSIGHT_API_ENABLE_BANK_CONFIG_API gates only the write operations on this resource.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)

Bank identifier

required
object (Config)

Fully resolved configuration with all hierarchical overrides applied (Python field names)

required
object (Overrides)

Bank-specific configuration overrides only (Python field names)

Response samples

Content type
application/json
{
  • "bank_id": "my-bank",
  • "config": {
    },
  • "overrides": {
    }
}

Update bank configuration

Update configuration overrides for a bank. Only hierarchical behavioral settings can be overridden (retention parameters, recall settings, etc.). Keys can be provided in Python field format (retain_extraction_mode) or environment variable format (HINDSIGHT_API_RETAIN_EXTRACTION_MODE).

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
required
object (Updates)

Configuration overrides. Keys can be in Python field format (retain_extraction_mode) or environment variable format (HINDSIGHT_API_RETAIN_EXTRACTION_MODE). Only hierarchical fields can be overridden per-bank.

property name*
additional property
any

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)

Bank identifier

required
object (Config)

Fully resolved configuration with all hierarchical overrides applied (Python field names)

required
object (Overrides)

Bank-specific configuration overrides only (Python field names)

Request samples

Content type
application/json
{
  • "updates": {
    }
}

Response samples

Content type
application/json
{
  • "bank_id": "my-bank",
  • "config": {
    },
  • "overrides": {
    }
}

Reset bank configuration

Reset bank configuration to defaults by removing all bank-specific overrides. The bank will then use global and tenant-level configuration only.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)

Bank identifier

required
object (Config)

Fully resolved configuration with all hierarchical overrides applied (Python field names)

required
object (Overrides)

Bank-specific configuration overrides only (Python field names)

Response samples

Content type
application/json
{
  • "bank_id": "my-bank",
  • "config": {
    },
  • "overrides": {
    }
}

Trigger consolidation

Run memory consolidation to create/update observations from recent memories.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
Any of
Array of Observation Scopes (strings) or Observation Scopes (null) (Observation Scopes)

Optional list of tag scopes to consolidate. Each scope is a list of tags. Only unconsolidated memories whose tags contain all tags in at least one scope will be processed. If omitted, all unconsolidated memories are processed.

Any of
Array
Array
string

Responses

Response Schema: application/json
operation_id
required
string (Operation Id)

ID of the async consolidation operation

deduplicated
boolean (Deduplicated)
Default: false

True if an existing pending task was reused

Request samples

Content type
application/json
Example
{
  • "observation_scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "operation_id": "string",
  • "deduplicated": false
}

Entities

List entities

List all entities (people, organizations, etc.) known by the bank, ordered by mention count. Supports pagination.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
limit
integer (Limit) >= 0
Default: 100

Maximum number of entities to return

offset
integer (Offset) >= 0
Default: 0

Offset for pagination

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Items)
total
required
integer (Total)
limit
required
integer (Limit)
offset
required
integer (Offset)

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "limit": 100,
  • "offset": 0,
  • "total": 150
}

Get entity co-occurrence graph

Return a graph of entities (nodes) and their co-occurrences (edges) for visualization.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
limit
integer (Limit) >= 0
Default: 1000

Maximum number of co-occurrence edges to return

min_count
integer (Min Count)
Default: 1

Minimum cooccurrence_count to include an edge

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Nodes)
required
Array of objects (Edges)
total_entities
required
integer (Total Entities)
total_edges
required
integer (Total Edges)
limit
required
integer (Limit)

Response samples

Content type
application/json
{
  • "edges": [
    ],
  • "limit": 1000,
  • "nodes": [
    ],
  • "total_edges": 1,
  • "total_entities": 2
}

Get entity details

Get detailed information about an entity including observations (mental model).

path Parameters
bank_id
required
string (Bank Id)
entity_id
required
string (Entity Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
id
required
string (Id)
canonical_name
required
string (Canonical Name)
mention_count
required
integer (Mention Count)
First Seen (string) or First Seen (null) (First Seen)
Last Seen (string) or Last Seen (null) (Last Seen)
Metadata (object) or Metadata (null) (Metadata)
required
Array of objects (Observations)

Response samples

Content type
application/json
{
  • "canonical_name": "John",
  • "first_seen": "2024-01-15T10:30:00Z",
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "last_seen": "2024-02-01T14:00:00Z",
  • "mention_count": 15,
  • "observations": [
    ]
}

Regenerate entity observations (deprecated) Deprecated

This endpoint is deprecated. Entity observations have been replaced by mental models.

path Parameters
bank_id
required
string (Bank Id)
entity_id
required
string (Entity Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
id
required
string (Id)
canonical_name
required
string (Canonical Name)
mention_count
required
integer (Mention Count)
First Seen (string) or First Seen (null) (First Seen)
Last Seen (string) or Last Seen (null) (Last Seen)
Metadata (object) or Metadata (null) (Metadata)
required
Array of objects (Observations)

Response samples

Content type
application/json
{
  • "canonical_name": "John",
  • "first_seen": "2024-01-15T10:30:00Z",
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "last_seen": "2024-02-01T14:00:00Z",
  • "mention_count": 15,
  • "observations": [
    ]
}

Mental Models

List mental models

List user-curated living documents that stay current.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Array of Tags (strings) or Tags (null) (Tags)

Filter by tags

tags_match
string (Tags Match)
Default: "any"
Enum: "any" "all" "exact"

How to match tags

detail
string (Detail)
Default: "metadata"
Enum: "metadata" "content" "full"

Detail level: 'metadata' (names/tags/staleness — the default), 'content' (adds content/config), 'full' (includes reflect_response). Content is opt-in: it is returned only when explicitly requested.

limit
integer (Limit) [ 1 .. 1000 ]
Default: 100
offset
integer (Offset) >= 0
Default: 0
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Items)
total
required
integer (Total)

Total number of mental models matching the filter (not just this page)

limit
required
integer (Limit)

Page size that was applied

offset
required
integer (Offset)

Offset that was applied

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Create mental model

Create a mental model by running reflect with the source query in the background. Returns an operation ID to track progress. The content is auto-generated by the reflect endpoint. Use the operations endpoint to check completion status.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Id (string) or Id (null) (Id)

Optional custom ID for the mental model (alphanumeric lowercase with hyphens)

name
required
string (Name)

Human-readable name for the mental model

source_query
required
string (Source Query)

The query to run to generate content

tags
Array of strings (Tags)
Default: []

Tags for scoped visibility

max_tokens
integer (Max Tokens) [ 256 .. 8192 ]
Default: 2048

Maximum tokens for generated content

object (MentalModelTrigger-Input)
Default: {}

Trigger settings

Responses

Response Schema: application/json
Mental Model Id (string) or Mental Model Id (null) (Mental Model Id)

ID of the created mental model

operation_id
required
string (Operation Id)

Operation ID to track refresh progress

Request samples

Content type
application/json
{
  • "id": "team-communication",
  • "max_tokens": 2048,
  • "name": "Team Communication Preferences",
  • "source_query": "How does the team prefer to communicate?",
  • "tags": [
    ],
  • "trigger": {
    }
}

Response samples

Content type
application/json
{
  • "mental_model_id": "string",
  • "operation_id": "string"
}

Get mental model

Get a specific mental model by ID.

path Parameters
bank_id
required
string (Bank Id)
mental_model_id
required
string (Mental Model Id)
query Parameters
detail
string (Detail)
Default: "full"
Enum: "metadata" "content" "full"

Detail level: 'metadata' (names/tags only), 'content' (adds content/config), 'full' (includes reflect_response)

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
id
required
string (Id)
bank_id
required
string (Bank Id)
name
required
string (Name)
Source Query (string) or Source Query (null) (Source Query)
Content (string) or Content (null) (Content)

The mental model content as well-formatted markdown (auto-generated from reflect endpoint)

tags
Array of strings (Tags)
Default: []
Max Tokens (integer) or Max Tokens (null) (Max Tokens)
MentalModelTrigger (object) or null
Last Refreshed At (string) or Last Refreshed At (null) (Last Refreshed At)

When a refresh last finished for this model — wall-clock, in ISO format. Advances on every refresh that completes, including one that found nothing new and preserved the content, and on a direct edit of content. A refresh that failed leaves it alone. This is the field to answer 'have I already refreshed this?'; it says nothing about whether the model is behind the data, which is last_memory_seen_at / is_stale.

Last Memory Seen At (string) or Last Memory Seen At (null) (Last Memory Seen At)

How far through the bank's memories this model is written — the newest in-scope memory the last refresh saw, in ISO format. Stands still when nothing in the model's scope has been written, however often it is refreshed. At or after the bank's last_memory_write_at (GET /stats) the model is provably up to date; when it is older, is_stale settles it against the model's own scope. Null for a model no refresh has stamped yet.

Created At (string) or Created At (null) (Created At)
Reflect Response (object) or Reflect Response (null) (Reflect Response)

Full reflect API response payload including based_on facts and observations

Is Stale (boolean) or Is Stale (null) (Is Stale)

True when memories matching this mental model's tag/fact_type scope have been written since last_memory_seen_at — the same check that decides whether a scheduled refresh does any work, so a model flagged here is one a refresh would actually rewrite. Populated on both the single read and the list. Deletions are not observed: removing an in-scope memory leaves no write behind, so it does not raise this flag.

Response samples

Content type
application/json
{
  • "id": "string",
  • "bank_id": "string",
  • "name": "string",
  • "source_query": "string",
  • "content": "string",
  • "tags": [ ],
  • "max_tokens": 0,
  • "trigger": {
    },
  • "last_refreshed_at": "string",
  • "last_memory_seen_at": "string",
  • "created_at": "string",
  • "reflect_response": { },
  • "is_stale": true
}

Update mental model

Update a mental model's name and/or source query.

path Parameters
bank_id
required
string (Bank Id)
mental_model_id
required
string (Mental Model Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)

New name for the mental model

Source Query (string) or Source Query (null) (Source Query)

New source query for the mental model

Max Tokens (integer) or Max Tokens (null) (Max Tokens)

Maximum tokens for generated content

Array of Tags (strings) or Tags (null) (Tags)

Tags for scoped visibility

MentalModelTrigger (object) or null

Trigger settings

Responses

Response Schema: application/json
id
required
string (Id)
bank_id
required
string (Bank Id)
name
required
string (Name)
Source Query (string) or Source Query (null) (Source Query)
Content (string) or Content (null) (Content)

The mental model content as well-formatted markdown (auto-generated from reflect endpoint)

tags
Array of strings (Tags)
Default: []
Max Tokens (integer) or Max Tokens (null) (Max Tokens)
MentalModelTrigger (object) or null
Last Refreshed At (string) or Last Refreshed At (null) (Last Refreshed At)

When a refresh last finished for this model — wall-clock, in ISO format. Advances on every refresh that completes, including one that found nothing new and preserved the content, and on a direct edit of content. A refresh that failed leaves it alone. This is the field to answer 'have I already refreshed this?'; it says nothing about whether the model is behind the data, which is last_memory_seen_at / is_stale.

Last Memory Seen At (string) or Last Memory Seen At (null) (Last Memory Seen At)

How far through the bank's memories this model is written — the newest in-scope memory the last refresh saw, in ISO format. Stands still when nothing in the model's scope has been written, however often it is refreshed. At or after the bank's last_memory_write_at (GET /stats) the model is provably up to date; when it is older, is_stale settles it against the model's own scope. Null for a model no refresh has stamped yet.

Created At (string) or Created At (null) (Created At)
Reflect Response (object) or Reflect Response (null) (Reflect Response)

Full reflect API response payload including based_on facts and observations

Is Stale (boolean) or Is Stale (null) (Is Stale)

True when memories matching this mental model's tag/fact_type scope have been written since last_memory_seen_at — the same check that decides whether a scheduled refresh does any work, so a model flagged here is one a refresh would actually rewrite. Populated on both the single read and the list. Deletions are not observed: removing an in-scope memory leaves no write behind, so it does not raise this flag.

Request samples

Content type
application/json
{
  • "max_tokens": 4096,
  • "name": "Updated Team Communication Preferences",
  • "source_query": "How does the team prefer to communicate?",
  • "tags": [
    ],
  • "trigger": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "bank_id": "string",
  • "name": "string",
  • "source_query": "string",
  • "content": "string",
  • "tags": [ ],
  • "max_tokens": 0,
  • "trigger": {
    },
  • "last_refreshed_at": "string",
  • "last_memory_seen_at": "string",
  • "created_at": "string",
  • "reflect_response": { },
  • "is_stale": true
}

Delete mental model

Delete a mental model.

path Parameters
bank_id
required
string (Bank Id)
mental_model_id
required
string (Mental Model Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Get mental model history

Get the refresh history of a mental model, showing content changes over time.

path Parameters
bank_id
required
string (Bank Id)
mental_model_id
required
string (Mental Model Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Refresh mental model

Submit an async task to re-run the source query through reflect and update the content.

path Parameters
bank_id
required
string (Bank Id)
mental_model_id
required
string (Mental Model Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
operation_id
required
string (Operation Id)
status
required
string (Status)

Response samples

Content type
application/json
{
  • "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "queued"
}

Dry-run mental model refresh (preview, no persistence)

Preview what a refresh would do to this mental model WITHOUT changing it — no content, structured document, watermark, or last_refreshed_at is written. Returns the mode the refresh ran in and why (delta silently falls back to full when there is no baseline or the source query changed), the resolved tag scope and time window it read, how many facts retrieval returned versus how many the reflect agent actually used, the delta operations it emitted, and a unified diff from the stored content to the content it would write.

This is the production refresh pipeline with two writes skipped — the content and the watermark — and nothing about it is configurable, so what it reports is what the next refresh will do. Because nothing is persisted, a delta dry run reads exactly the window the next real refresh would, and repeating it reads that same window again.

It costs the same LLM tokens as a refresh and is validated the same way.

path Parameters
bank_id
required
string (Bank Id)
mental_model_id
required
string (Mental Model Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
mental_model_id
required
string (Mental Model Id)

The mental model previewed.

name
required
string (Name)

Display name of the mental model.

requested_mode
required
string (Requested Mode)
Enum: "full" "delta"

The mode asked for (from the model's trigger, or overridden).

effective_mode
required
string (Effective Mode)
Enum: "full" "delta"

The mode the refresh actually ran in.

Mode Fallback Reason (string) or Mode Fallback Reason (null) (Mode Fallback Reason)

Why delta was requested but not applied, if that happened.

outcome
required
string (Outcome)
Enum: "content_written" "content_unchanged" "content_preserved_no_new_facts" "refresh_failed_empty_candidate" "refresh_failed_delta_not_applied"

What a real refresh would do with the document.

would_persist
required
boolean (Would Persist)

Whether a real refresh would write new content.

required
object (MentalModelRefreshScope)

The resolved memory scope.

required
object (MentalModelRefreshWindow)

The snapshot window read from.

required
object (MentalModelFactCounts)

Facts retrieved versus actually used.

object (Based On)

The evidence this run would ground the document on, keyed by fact type — the same shape a refresh persists under reflect_response.based_on. Returned so a preview can show its sources without having to write them anywhere.

current_content
required
string (Current Content)

The model's content as it stands now.

candidate_content
required
string (Candidate Content)

Raw reflect synthesis, before any delta operations.

preview_content
required
string (Preview Content)

The content a real refresh would store: the delta-edited document, or the candidate in full mode.

diff
required
string (Diff)

Unified diff from current_content to preview_content. Empty when identical.

MentalModelDeltaOperations (object) or null

Structured operations emitted, in delta mode.

MentalModelRetraction (object) or null

Facts the document cites that no longer exist, and what a real refresh would do about them.

required
object (MentalModelRefreshTrace)

Execution trace of the run, always included for a dry run.

object (TokenUsage)

Token usage across the run's LLM calls.

duration_ms
integer (Duration Ms)
Default: 0

Wall-clock duration of the run.

warnings
Array of strings (Warnings)

Conditions worth a human's attention, in plain language.

Response samples

Content type
application/json
{
  • "effective_mode": "full",
  • "facts": {
    },
  • "mental_model_id": "coding-style",
  • "mode_fallback_reason": "source_query_changed",
  • "name": "Coding Style",
  • "outcome": "content_written",
  • "requested_mode": "delta",
  • "warnings": [ ],
  • "would_persist": true
}

Clear mental model content

Clear a mental model's content so the next refresh performs a full re-synthesis. This is useful for delta-mode models that have accumulated drift over many incremental refreshes. After clearing, call the /refresh endpoint to trigger a clean full rebuild.

path Parameters
bank_id
required
string (Bank Id)
mental_model_id
required
string (Mental Model Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
id
required
string (Id)
bank_id
required
string (Bank Id)
name
required
string (Name)
Source Query (string) or Source Query (null) (Source Query)
Content (string) or Content (null) (Content)

The mental model content as well-formatted markdown (auto-generated from reflect endpoint)

tags
Array of strings (Tags)
Default: []
Max Tokens (integer) or Max Tokens (null) (Max Tokens)
MentalModelTrigger (object) or null
Last Refreshed At (string) or Last Refreshed At (null) (Last Refreshed At)

When a refresh last finished for this model — wall-clock, in ISO format. Advances on every refresh that completes, including one that found nothing new and preserved the content, and on a direct edit of content. A refresh that failed leaves it alone. This is the field to answer 'have I already refreshed this?'; it says nothing about whether the model is behind the data, which is last_memory_seen_at / is_stale.

Last Memory Seen At (string) or Last Memory Seen At (null) (Last Memory Seen At)

How far through the bank's memories this model is written — the newest in-scope memory the last refresh saw, in ISO format. Stands still when nothing in the model's scope has been written, however often it is refreshed. At or after the bank's last_memory_write_at (GET /stats) the model is provably up to date; when it is older, is_stale settles it against the model's own scope. Null for a model no refresh has stamped yet.

Created At (string) or Created At (null) (Created At)
Reflect Response (object) or Reflect Response (null) (Reflect Response)

Full reflect API response payload including based_on facts and observations

Is Stale (boolean) or Is Stale (null) (Is Stale)

True when memories matching this mental model's tag/fact_type scope have been written since last_memory_seen_at — the same check that decides whether a scheduled refresh does any work, so a model flagged here is one a refresh would actually rewrite. Populated on both the single read and the list. Deletions are not observed: removing an in-scope memory leaves no write behind, so it does not raise this flag.

Response samples

Content type
application/json
{
  • "id": "string",
  • "bank_id": "string",
  • "name": "string",
  • "source_query": "string",
  • "content": "string",
  • "tags": [ ],
  • "max_tokens": 0,
  • "trigger": {
    },
  • "last_refreshed_at": "string",
  • "last_memory_seen_at": "string",
  • "created_at": "string",
  • "reflect_response": { },
  • "is_stale": true
}

Knowledge Base

Get the knowledge-base tree

Return the knowledge base as a nested tree of folders and pages.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Roots)
Array
id
required
string (Id)
kind
required
string (Kind)
Enum: "folder" "page"
name
required
string (Name)
Parent Id (string) or Parent Id (null) (Parent Id)
Mental Model Id (string) or Mental Model Id (null) (Mental Model Id)

Backing mental model id (pages only).

managed
boolean (Managed)
Default: false

Client-set flag: true = system-owned, false = hand-authored.

Description (string) or Description (null) (Description)

Page source query (the page's description).

tags
Array of strings (Tags)
Default: []
Timestamp (string) or Timestamp (null) (Timestamp)

Last refresh (page) or last update (folder).

Is Stale (boolean) or Is Stale (null) (Is Stale)

Pages only, populated by the tree endpoint. True when a memory in this page's scope — its tags and fact types — has been written since the page last read the memories. That is the same check a scheduled refresh runs before spending an LLM call, so a flagged page is one a refresh would actually rewrite. Deletions are not observed: removing an in-scope memory leaves no write behind, so it does not raise this flag.

MentalModelTrigger (object) or null

Pages only: the page's refresh settings — when it rebuilds itself (refresh_after_consolidation or refresh_cron), in which mode, and over which facts. This is the EFFECTIVE policy: a setting the page never stored is reported at its default, so compare the fields you care about rather than the whole object against a patch you sent. Absent on folders, which have no backing mental model, and on a page with no trigger stored.

children
Array of objects (Children)
Default: []

Response samples

Content type
application/json
{
  • "roots": [
    ]
}

Create a knowledge-base folder

Create a folder, optionally nested under a parent folder.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
name
required
string (Name)
Parent Id (string) or Parent Id (null) (Parent Id)

Responses

Response Schema: application/json
id
required
string (Id)
kind
required
string (Kind)
Enum: "folder" "page"
name
required
string (Name)
Parent Id (string) or Parent Id (null) (Parent Id)
Mental Model Id (string) or Mental Model Id (null) (Mental Model Id)

Backing mental model id (pages only).

managed
boolean (Managed)
Default: false

Client-set flag: true = system-owned, false = hand-authored.

Description (string) or Description (null) (Description)

Page source query (the page's description).

tags
Array of strings (Tags)
Default: []
Timestamp (string) or Timestamp (null) (Timestamp)

Last refresh (page) or last update (folder).

Is Stale (boolean) or Is Stale (null) (Is Stale)

Pages only, populated by the tree endpoint. True when a memory in this page's scope — its tags and fact types — has been written since the page last read the memories. That is the same check a scheduled refresh runs before spending an LLM call, so a flagged page is one a refresh would actually rewrite. Deletions are not observed: removing an in-scope memory leaves no write behind, so it does not raise this flag.

MentalModelTrigger (object) or null

Pages only: the page's refresh settings — when it rebuilds itself (refresh_after_consolidation or refresh_cron), in which mode, and over which facts. This is the EFFECTIVE policy: a setting the page never stored is reported at its default, so compare the fields you care about rather than the whole object against a patch you sent. Absent on folders, which have no backing mental model, and on a page with no trigger stored.

children
Array of objects (Children)
Default: []

Request samples

Content type
application/json
{
  • "name": "string",
  • "parent_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "folder",
  • "name": "string",
  • "parent_id": "string",
  • "mental_model_id": "string",
  • "managed": false,
  • "description": "string",
  • "tags": [ ],
  • "timestamp": "string",
  • "is_stale": true,
  • "trigger": {
    },
  • "children": [ ]
}

Create a knowledge-base page

Create a page (a mental model + tree node). Content is generated asynchronously; use the returned operation_id to track completion.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
name
required
string (Name)
source_query
required
string (Source Query)
Parent Id (string) or Parent Id (null) (Parent Id)
Array of Tags (strings) or Tags (null) (Tags)

Tags that SCOPE which memories this page is built from — not labels. Every tag here, including a type:<x> tag used to set the page's rendered type, is part of the filter. By default a tagged page matches with all_strict: a memory must carry EVERY one of these tags, and untagged memories are excluded entirely. Tags invented for the page (a topic, a document type) therefore match nothing unless your memories were retained with those exact tags, and the page generates as 'I don't have information about this'. Omit this field to build the page from the whole bank, or set trigger.tags_match to 'all' to require the tags while still including untagged memories.

Max Tokens (integer) or Max Tokens (null) (Max Tokens)
MentalModelTrigger (object) or null

Responses

Response Schema: application/json
page_id
required
string (Page Id)
mental_model_id
required
string (Mental Model Id)
Operation Id (string) or Operation Id (null) (Operation Id)

Request samples

Content type
application/json
{
  • "name": "string",
  • "source_query": "string",
  • "parent_id": "string",
  • "tags": [
    ],
  • "max_tokens": 0,
  • "trigger": {
    }
}

Response samples

Content type
application/json
{
  • "page_id": "string",
  • "mental_model_id": "string",
  • "operation_id": "string"
}

Export the knowledge base as a markdown bundle

Return a portable markdown bundle: a nested index.md, one .md per page, and history logs.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Files)
Array
path
required
string (Path)
content
required
string (Content)

Response samples

Content type
application/json
{
  • "files": [
    ]
}

Hybrid search over knowledge pages (BM25 + vector)

Doc-level hybrid search across a bank's knowledge pages: a full-text (BM25) match and a vector-similarity match, Reciprocal-Rank-Fusion fused. No reranker — tuned for latency.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
q
required
string (Q) non-empty

Search query

limit
integer (Limit) [ 1 .. 50 ]
Default: 10

Maximum results to return

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Results)
total
required
integer (Total)

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 0
}

Get a knowledge-base page

Return a single page as a markdown document (frontmatter + markdown body).

path Parameters
bank_id
required
string (Bank Id)
page_id
required
string (Page Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
id
required
string (Id)
name
required
string (Name)
type
required
string (Type)

Page type — from a type:<x> tag, else 'knowledge-page'.

Description (string) or Description (null) (Description)

The source query that rebuilds the page.

tags
Array of strings (Tags)
Default: []
Timestamp (string) or Timestamp (null) (Timestamp)

Last refresh time (falls back to creation).

Body (string) or Body (null) (Body)

The page's synthesized markdown body.

markdown
required
string (Markdown)

The full markdown document: YAML frontmatter + markdown body.

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "type": "string",
  • "description": "string",
  • "tags": [ ],
  • "timestamp": "string",
  • "body": "string",
  • "markdown": "string"
}

Rename/move a knowledge-base node or update a page's options

Rename a node (set name), move it under another folder (set parent_id, null for the root), and/or update a page's options (source_query, tags, max_tokens, trigger). Changing source_query schedules an async refresh so the page rebuilds against the new question. trigger is applied as a patch: the fields you send are updated and the rest keep the page's current values.

path Parameters
bank_id
required
string (Bank Id)
node_id
required
string (Node Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Parent Id (string) or Parent Id (null) (Parent Id)
Source Query (string) or Source Query (null) (Source Query)
Array of Tags (strings) or Tags (null) (Tags)

Replaces the page's tags, which SCOPE which memories it is built from. Pass [] to clear them and rebuild the page from the whole bank — the fix when a page generates 'I don't have information about this' because its tags match no memory. See the matching rules on this field in CreatePageRequest; trigger.tags_match widens them.

Max Tokens (integer) or Max Tokens (null) (Max Tokens)
MentalModelTrigger (object) or null

Refresh settings to change. Applied as a patch: only the fields present in this object are updated, and the rest keep the page's current values — so moving a page onto a schedule does not reset how it refreshes. Setting refresh_cron clears refresh_after_consolidation and vice versa, since a page refreshes on one or the other, never both.

Responses

Response Schema: application/json
id
required
string (Id)
kind
required
string (Kind)
Enum: "folder" "page"
name
required
string (Name)
Parent Id (string) or Parent Id (null) (Parent Id)
Mental Model Id (string) or Mental Model Id (null) (Mental Model Id)

Backing mental model id (pages only).

managed
boolean (Managed)
Default: false

Client-set flag: true = system-owned, false = hand-authored.

Description (string) or Description (null) (Description)

Page source query (the page's description).

tags
Array of strings (Tags)
Default: []
Timestamp (string) or Timestamp (null) (Timestamp)

Last refresh (page) or last update (folder).

Is Stale (boolean) or Is Stale (null) (Is Stale)

Pages only, populated by the tree endpoint. True when a memory in this page's scope — its tags and fact types — has been written since the page last read the memories. That is the same check a scheduled refresh runs before spending an LLM call, so a flagged page is one a refresh would actually rewrite. Deletions are not observed: removing an in-scope memory leaves no write behind, so it does not raise this flag.

MentalModelTrigger (object) or null

Pages only: the page's refresh settings — when it rebuilds itself (refresh_after_consolidation or refresh_cron), in which mode, and over which facts. This is the EFFECTIVE policy: a setting the page never stored is reported at its default, so compare the fields you care about rather than the whole object against a patch you sent. Absent on folders, which have no backing mental model, and on a page with no trigger stored.

children
Array of objects (Children)
Default: []

Request samples

Content type
application/json
{
  • "name": "string",
  • "parent_id": "string",
  • "source_query": "string",
  • "tags": [
    ],
  • "max_tokens": 0,
  • "trigger": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "folder",
  • "name": "string",
  • "parent_id": "string",
  • "mental_model_id": "string",
  • "managed": false,
  • "description": "string",
  • "tags": [ ],
  • "timestamp": "string",
  • "is_stale": true,
  • "trigger": {
    },
  • "children": [ ]
}

Delete a knowledge-base node

Delete a folder or page and its whole subtree (pages' mental models are removed too).

path Parameters
bank_id
required
string (Bank Id)
node_id
required
string (Node Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Directives

List directives

List directive definitions. Unlike reflect, an omitted tag filter returns all directives.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Array of Tags (strings) or Tags (null) (Tags)

Filter directives by execution scope. Omit or pass [] to list all directives.

tags_match
string (Tags Match)
Default: "any"
Enum: "any" "all" "exact"

How tagged directives match the requested scope. Untagged/global directives are included.

active_only
boolean (Active Only)
Default: true

Only return active directives

limit
integer (Limit) [ 1 .. 1000 ]
Default: 100
offset
integer (Offset) >= 0
Default: 0
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Items)
total
required
integer (Total)

Total number of directives matching the filter (not just this page)

limit
required
integer (Limit)

Page size that was applied

offset
required
integer (Offset)

Offset that was applied

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Create directive

Create a global or tag-scoped hard rule for reflect prompts.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
name
required
string (Name)

Human-readable name for the directive

content
required
string (Content)

The directive text to inject into prompts

priority
integer (Priority)
Default: 0

Higher priority directives are injected first

is_active
boolean (Is Active)
Default: true

Whether this directive is active

tags
Array of strings (Tags)
Default: []

Directive execution scope. Empty means global; non-empty requires a matching reflect scope.

Responses

Response Schema: application/json
id
required
string (Id)
bank_id
required
string (Bank Id)
name
required
string (Name)
content
required
string (Content)
priority
integer (Priority)
Default: 0
is_active
boolean (Is Active)
Default: true
tags
Array of strings (Tags)
Default: []
Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)

Request samples

Content type
application/json
{
  • "name": "string",
  • "content": "string",
  • "priority": 0,
  • "is_active": true,
  • "tags": [ ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "bank_id": "string",
  • "name": "string",
  • "content": "string",
  • "priority": 0,
  • "is_active": true,
  • "tags": [ ],
  • "created_at": "string",
  • "updated_at": "string"
}

Get directive

Get a specific directive by ID.

path Parameters
bank_id
required
string (Bank Id)
directive_id
required
string (Directive Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
id
required
string (Id)
bank_id
required
string (Bank Id)
name
required
string (Name)
content
required
string (Content)
priority
integer (Priority)
Default: 0
is_active
boolean (Is Active)
Default: true
tags
Array of strings (Tags)
Default: []
Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)

Response samples

Content type
application/json
{
  • "id": "string",
  • "bank_id": "string",
  • "name": "string",
  • "content": "string",
  • "priority": 0,
  • "is_active": true,
  • "tags": [ ],
  • "created_at": "string",
  • "updated_at": "string"
}

Update directive

Update a directive's properties.

path Parameters
bank_id
required
string (Bank Id)
directive_id
required
string (Directive Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)

New name

Content (string) or Content (null) (Content)

New content

Priority (integer) or Priority (null) (Priority)

New priority

Is Active (boolean) or Is Active (null) (Is Active)

New active status

Array of Tags (strings) or Tags (null) (Tags)

New tags

Responses

Response Schema: application/json
id
required
string (Id)
bank_id
required
string (Bank Id)
name
required
string (Name)
content
required
string (Content)
priority
integer (Priority)
Default: 0
is_active
boolean (Is Active)
Default: true
tags
Array of strings (Tags)
Default: []
Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)

Request samples

Content type
application/json
{
  • "name": "string",
  • "content": "string",
  • "priority": 0,
  • "is_active": true,
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "bank_id": "string",
  • "name": "string",
  • "content": "string",
  • "priority": 0,
  • "is_active": true,
  • "tags": [ ],
  • "created_at": "string",
  • "updated_at": "string"
}

Delete directive

Delete a directive.

path Parameters
bank_id
required
string (Bank Id)
directive_id
required
string (Directive Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Documents

List documents

List documents with pagination and optional search, most recently written first (updated_at descending). Documents are the source content from which memory units are extracted.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Q (string) or Q (null) (Q)

Case-insensitive substring filter on document ID (e.g. 'report' matches 'report-2024')

Array of Tags (strings) or Tags (null) (Tags)

Filter documents by tags

tags_match
string (Tags Match)
Default: "any_strict"

How to match tags: 'any', 'all', 'any_strict', 'all_strict'

limit
integer (Limit) >= 0
Default: 100
offset
integer (Offset) >= 0
Default: 0
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Items)
total
required
integer (Total)
limit
required
integer (Limit)
offset
required
integer (Offset)

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "limit": 100,
  • "offset": 0,
  • "total": 50
}

List document chunks

List all chunks for a given document, ordered by chunk index.

path Parameters
bank_id
required
string (Bank Id)
document_id
required
string (Document Id)
query Parameters
limit
integer (Limit) [ 1 .. 1000 ]
Default: 100

Maximum number of chunks to return

offset
integer (Offset) >= 0
Default: 0

Offset for pagination

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Items)
total
required
integer (Total)
limit
required
integer (Limit)
offset
required
integer (Offset)

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Reprocess document

Re-run the retain pipeline on an existing document without changing its content. This deletes the existing memory units and re-extracts facts using the current engine configuration. Useful when the LLM model, chunking strategy, or extraction settings have changed.

path Parameters
bank_id
required
string (Bank Id)
document_id
required
string (Document Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
success
required
boolean (Success)
operation_id
required
string (Operation Id)
items_count
required
integer (Items Count)

Response samples

Content type
application/json
{
  • "success": true,
  • "operation_id": "string",
  • "items_count": 0
}

Get document details

Get a specific document including its original text

path Parameters
bank_id
required
string (Bank Id)
document_id
required
string (Document Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
id
required
string (Id)
bank_id
required
string (Bank Id)
required
Original Text (string) or Original Text (null) (Original Text)
required
Content Hash (string) or Content Hash (null) (Content Hash)
created_at
required
string (Created At)
updated_at
required
string (Updated At)
memory_unit_count
required
integer (Memory Unit Count)
Nodes By Fact Type (object) or Nodes By Fact Type (null) (Nodes By Fact Type)

Memory count per fact type (world, experience, observation)

tags
Array of strings (Tags)
Default: []

Tags associated with this document

Document Metadata (object) or Document Metadata (null) (Document Metadata)

Document metadata

Retain Params (object) or Retain Params (null) (Retain Params)

Parameters used during retain

Observation Scopes (string) or Array of Observation Scopes (strings) or Observation Scopes (null) (Observation Scopes)

The observation_scopes spec configured at retain time (e.g. 'all_combinations', 'per_tag', or explicit tag-set lists), captured into retain_params. None when none was set (default 'combined' scoping) or for documents retained before this was captured.

Array of Attachments (objects) or Attachments (null) (Attachments)

Attachments referenced by this document, when it was retained with inline content. Each carries a bank-scoped url serving the original bytes. Omitted when there are none.

Response samples

Content type
application/json
{
  • "bank_id": "user123",
  • "content_hash": "abc123",
  • "created_at": "2024-01-15T10:30:00Z",
  • "document_metadata": {
    },
  • "id": "session_1",
  • "memory_unit_count": 15,
  • "original_text": "Full document text here...",
  • "retain_params": {
    },
  • "tags": [
    ],
  • "updated_at": "2024-01-15T10:30:00Z"
}

Update document

Update mutable fields on a document without re-processing its content.

Tags (tags): The array REPLACES the document's tags, it is not merged into them — send the complete set you want the document to end up with, and any tag you leave out is dropped. An empty array ([]) therefore clears every tag; only omitting the field entirely is rejected (422).

The new tags are propagated to all associated memory units. Observations derived from those units are invalidated and queued for re-consolidation under the new tags. Co-source memories from other documents that shared those observations are also reset. Tags are compared as a set, so re-sending the tags a document already has (in any order) changes nothing and queues no re-consolidation.

At least one field must be provided.

path Parameters
bank_id
required
string (Bank Id)
document_id
required
string (Document Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Array of Tags (strings) or Tags (null) (Tags)

The complete new set of tags for the document and its memory units — this REPLACES the existing tags rather than adding to them, so omitting a tag drops it and [] clears them all. Triggers observation invalidation and re-consolidation.

Any of
Array
string

Responses

Response Schema: application/json
success
boolean (Success)
Default: true

Request samples

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true
}

Delete a document

Delete a document and all its associated memory units and links.

This will cascade delete:

  • The document itself
  • All memory units extracted from this document
  • All links (temporal, semantic, entity) associated with those memory units

This operation cannot be undone.

path Parameters
bank_id
required
string (Bank Id)
document_id
required
string (Document Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
success
required
boolean (Success)
message
required
string (Message)
document_id
required
string (Document Id)
memory_units_deleted
required
integer (Memory Units Deleted)

Response samples

Content type
application/json
{
  • "document_id": "session_1",
  • "memory_units_deleted": 5,
  • "message": "Document 'session_1' and 5 associated memory units deleted successfully",
  • "success": true
}

Get chunk details

Get a specific chunk by its ID

path Parameters
chunk_id
required
string (Chunk Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
chunk_id
required
string (Chunk Id)
document_id
required
string (Document Id)
bank_id
required
string (Bank Id)
chunk_index
required
integer (Chunk Index)
chunk_text
required
string (Chunk Text)
created_at
required
string (Created At)
Array of Attachments (objects) or Attachments (null) (Attachments)

Attachments referenced by this chunk's text, when it was retained with inline content. Each carries a bank-scoped url serving the original bytes. Omitted when there are none.

Response samples

Content type
application/json
{
  • "bank_id": "user123",
  • "chunk_id": "user123_session_1_0",
  • "chunk_index": 0,
  • "chunk_text": "This is the first chunk of the document...",
  • "created_at": "2024-01-15T10:30:00Z",
  • "document_id": "session_1"
}

Operations

List async operations

Get a list of async operations for a specific agent, with optional filtering by status and operation type. Results are sorted by most recent first.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Status (string) or Status (null) (Status)

Filter by status: pending, processing, completed, failed, or cancelled

Type (string) or Type (null) (Type)

Filter by operation type: retain, consolidation, refresh_mental_model, file_convert_retain, webhook_delivery

limit
integer (Limit) [ 1 .. 100 ]
Default: 20

Maximum number of operations to return

offset
integer (Offset) >= 0
Default: 0

Number of operations to skip

exclude_parents
boolean (Exclude Parents)
Default: false

Exclude parent batch operations from results

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
total
required
integer (Total)
limit
required
integer (Limit)
offset
required
integer (Offset)
required
Array of objects (Operations)

Response samples

Content type
application/json
{
  • "bank_id": "user123",
  • "limit": 20,
  • "offset": 0,
  • "operations": [
    ],
  • "total": 150
}

Get operation status

Get the status of a specific async operation. Returns 'pending', 'processing', 'completed', 'failed', or 'cancelled'. Completed operations remain queryable with their payload for the configured retention window and are pruned afterward.

path Parameters
bank_id
required
string (Bank Id)
operation_id
required
string (Operation Id)
query Parameters
include_payload
boolean (Include Payload)
Default: false

Include the raw task payload (submission params) in the response. May be large.

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
operation_id
required
string (Operation Id)
status
required
string (Status)
Enum: "pending" "processing" "completed" "failed" "cancelled" "not_found"
Operation Type (string) or Operation Type (null) (Operation Type)
Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)
Completed At (string) or Completed At (null) (Completed At)
Error Message (string) or Error Message (null) (Error Message)
Retry Count (integer) or Retry Count (null) (Retry Count)

Number of times this operation has been retried after failure.

Next Retry At (string) or Next Retry At (null) (Next Retry At)

When the worker will next attempt this operation. For a pending operation, a value in the future indicates the task is parked — a refresh_mental_model held back by min_refresh_interval_seconds, or an extension raising DeferOperation — rather than awaiting immediate pickup.

OperationProgress (object) or null

Last-known progress snapshot for a running operation; null if none was recorded.

Result Metadata (object) or Result Metadata (null) (Result Metadata)

Internal metadata for debugging. Structure may change without notice. Not for production use.

RefreshMentalModelOperationDetails (object) or null

Typed, per-operation-type outcome detail, discriminated by its own operation_type. Populated for refresh_mental_model operations that have finished; null for operation types that report no typed detail, for operations still in flight, and for operations recorded before this field existed. Unlike result_metadata this is a supported field — new operation types add their own shape here rather than flattening fields onto the operation.

Array of Child Operations (objects) or Child Operations (null) (Child Operations)

Child operations for batch operations (if applicable)

Task Payload (object) or Task Payload (null) (Task Payload)

Raw task payload (params the operation was submitted with). Only populated when include_payload=true.

Response samples

Content type
application/json
{
  • "completed_at": "2024-01-15T10:31:30Z",
  • "created_at": "2024-01-15T10:30:00Z",
  • "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  • "operation_type": "refresh_mental_model",
  • "status": "completed",
  • "updated_at": "2024-01-15T10:31:30Z"
}

Cancel a pending or in-flight async operation

Cancel a queued or running async operation. A 'pending' operation is never started. A 'processing' one is cancelled cooperatively: the row is marked 'cancelled' immediately and the worker running it stops at its next checkpoint, so work already in flight may finish the batch it is on. This also clears operations stranded in 'processing' by a crashed worker. Returns 409 for operations that already reached a terminal state.

path Parameters
bank_id
required
string (Bank Id)
operation_id
required
string (Operation Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
success
required
boolean (Success)
message
required
string (Message)
operation_id
required
string (Operation Id)

Response samples

Content type
application/json
{
  • "message": "Operation 550e8400-e29b-41d4-a716-446655440000 cancelled",
  • "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  • "success": true
}

Retry a failed async operation

Re-queue a failed async operation so the worker picks it up again

path Parameters
bank_id
required
string (Bank Id)
operation_id
required
string (Operation Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
success
required
boolean (Success)
message
required
string (Message)
operation_id
required
string (Operation Id)

Response samples

Content type
application/json
{
  • "message": "Operation 550e8400-e29b-41d4-a716-446655440000 queued for retry",
  • "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  • "success": true
}

Delete a terminal async operation

Permanently remove a failed, cancelled, or completed async operation record

path Parameters
bank_id
required
string (Bank Id)
operation_id
required
string (Operation Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
success
required
boolean (Success)
message
required
string (Message)
operation_id
required
string (Operation Id)

Response samples

Content type
application/json
{
  • "message": "Operation 550e8400-e29b-41d4-a716-446655440000 deleted",
  • "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  • "success": true
}

Bank Templates

Import bank template

Import a bank template manifest to create or update a bank's configuration, mental models, and directives. If the bank does not exist it is created. Config fields are applied as per-bank overrides. Mental models are matched by id, directives by name — existing ones are updated, new ones are created. Use dry_run=true to validate the manifest without applying changes.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
dry_run
boolean (Dry Run)
Default: false

Validate only, do not apply changes

header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
version
required
string (Version)

Manifest schema version (currently '1')

BankTemplateConfig (object) or null

Bank configuration to apply. Omit to leave config unchanged.

Array of Mental Models (objects) or Mental Models (null) (Mental Models)

Mental models to create or update (matched by id). Omit to leave unchanged.

Array of Directives (objects) or Directives (null) (Directives)

Directives to create or update (matched by name). Omit to leave unchanged.

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)

Bank that was imported into

config_applied
required
boolean (Config Applied)

Whether bank config was updated

mental_models_created
Array of strings (Mental Models Created)
Default: []

IDs of newly created mental models

mental_models_updated
Array of strings (Mental Models Updated)
Default: []

IDs of updated mental models

directives_created
Array of strings (Directives Created)
Default: []

Names of newly created directives

directives_updated
Array of strings (Directives Updated)
Default: []

Names of updated directives

operation_ids
Array of strings (Operation Ids)
Default: []

Operation IDs for mental model content generation (async)

dry_run
boolean (Dry Run)
Default: false

True if this was a validation-only run

Request samples

Content type
application/json
{
  • "bank": {
    },
  • "directives": [
    ],
  • "mental_models": [
    ],
  • "version": "1"
}

Response samples

Content type
application/json
{
  • "bank_id": "string",
  • "config_applied": true,
  • "mental_models_created": [ ],
  • "mental_models_updated": [ ],
  • "directives_created": [ ],
  • "directives_updated": [ ],
  • "operation_ids": [ ],
  • "dry_run": false
}

Export bank template

Export a bank's current configuration, mental models, and directives as a template manifest. The exported manifest can be imported into another bank to replicate the setup.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
version
required
string (Version)

Manifest schema version (currently '1')

BankTemplateConfig (object) or null

Bank configuration to apply. Omit to leave config unchanged.

Array of Mental Models (objects) or Mental Models (null) (Mental Models)

Mental models to create or update (matched by id). Omit to leave unchanged.

Array of Directives (objects) or Directives (null) (Directives)

Directives to create or update (matched by name). Omit to leave unchanged.

Response samples

Content type
application/json
{
  • "bank": {
    },
  • "directives": [
    ],
  • "mental_models": [
    ],
  • "version": "1"
}

Get bank template JSON Schema

Returns the JSON Schema for the bank template manifest format. Use this to validate template manifests before importing.

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Document Transfer

Export documents (removed — use POST .../document-transfer/export) Deprecated

Removed. The synchronous whole-bank export loaded the entire bank into memory and held a database connection for the full request, which could exhaust memory and take down the shared API on large banks. Use the asynchronous POST /v1/default/banks/{bank_id}/document-transfer/export instead: it returns an operation_id, runs the export in the background, and exposes a download URL on completion.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Import documents (async)

Submit a transfer archive (produced by the export endpoint) for import into a bank. Runs as a background operation: facts are re-embedded with the target bank's embedding model and entities are re-resolved — no LLM extraction. Returns an operation_id; poll GET /v1/default/banks/{bank_id}/operations/{operation_id} for status and the imported/skipped counts in result_metadata. Use on_conflict to control existing document ids: skip (default), replace, or new-id.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
on_conflict
string (On Conflict)
Default: "skip"

skip | replace | new-id

header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: multipart/form-data
required
file
required
string <binary> (File)

Transfer ZIP archive

Responses

Response samples

Content type
application/json
{
  • "operation_id": "string",
  • "status": "pending"
}

Export documents (async)

Submit an async export of a bank's documents (extracted facts, entity names, causal links, chunks) as a transfer ZIP archive. Embeddings and database ids are not included — importing re-embeds with the target bank's model and re-resolves entities. Runs as a background operation to avoid pinning the API on large banks. Returns an operation_id; poll GET /v1/default/banks/{bank_id}/operations/{operation_id}. On completion the operation's result_metadata carries download_url (fetch the ZIP from GET /v1/default/files/download/{key}), storage_key, byte_size, and filename. Pass document_id query params to export specific documents, or omit to export the whole bank; include_observations=true carries consolidated observations and include_knowledge_base=true carries Mental Models plus Knowledge Pages (all whole-bank export only).

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Array of Document Id (strings) or Document Id (null) (Document Id)

Document id(s) to export; omit for all

include_observations
boolean (Include Observations)
Default: false

Also export consolidated observations (restored on import; whole-bank only)

include_knowledge_base
boolean (Include Knowledge Base)
Default: false

Also export Mental Models and Knowledge Pages (restored on import; whole-bank only)

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response samples

Content type
application/json
{
  • "operation_id": "string",
  • "status": "pending"
}

Download a stored file (async export archive)

Stream a file previously written to file storage — currently the transfer ZIP produced by an async document export. The key comes from the export operation's result_metadata (storage_key / download_url). Access is authorized against the bank the key belongs to.

path Parameters
key
required
string (Key)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema:
any

Response samples

Content type
null

Webhooks

Register webhook

Register a webhook endpoint to receive event notifications for this bank.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
url
required
string (Url)

HTTP(S) endpoint URL to deliver events to

Secret (string) or Secret (null) (Secret)

HMAC-SHA256 signing secret (optional)

event_types
Array of strings (Event Types)
Default: ["consolidation.completed"]

List of event types to deliver. Supported: 'retain.completed', 'consolidation.completed', 'memory_defense.triggered'.

enabled
boolean (Enabled)
Default: true

Whether this webhook is active

object (WebhookHttpConfig)

HTTP delivery configuration (method, timeout, headers, params)

Responses

Response Schema: application/json
id
required
string (Id)
required
Bank Id (string) or Bank Id (null) (Bank Id)
url
required
string (Url)
Secret (string) or Secret (null) (Secret)

Signing secret (redacted in responses)

event_types
required
Array of strings (Event Types)
enabled
required
boolean (Enabled)
object (WebhookHttpConfig)

HTTP delivery configuration for a webhook.

Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)

Request samples

Content type
application/json
{
  • "url": "string",
  • "secret": "string",
  • "event_types": [
    ],
  • "enabled": true,
  • "http_config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "bank_id": "string",
  • "url": "string",
  • "secret": "string",
  • "event_types": [
    ],
  • "enabled": true,
  • "http_config": {
    },
  • "created_at": "string",
  • "updated_at": "string"
}

List webhooks

List the webhooks registered for a bank, oldest first. Paged: total reports every webhook on the bank.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
limit
integer (Limit) [ 0 .. 1000 ]
Default: 100

Maximum number of webhooks to return

offset
integer (Offset) >= 0
Default: 0

Offset for pagination

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Items)
total
required
integer (Total)

Total number of webhooks on the bank (ignores limit/offset)

limit
required
integer (Limit)

Maximum number of webhooks returned in this page

offset
required
integer (Offset)

Offset this page started at

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "total": 0,
  • "limit": 0,
  • "offset": 0
}

Delete webhook

Remove a registered webhook.

path Parameters
bank_id
required
string (Bank Id)
webhook_id
required
string (Webhook Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
success
required
boolean (Success)
Message (string) or Message (null) (Message)
Deleted Count (integer) or Deleted Count (null) (Deleted Count)

Response samples

Content type
application/json
{
  • "deleted_count": 10,
  • "message": "Deleted successfully",
  • "success": true
}

Update webhook

Update one or more fields of a registered webhook. Only provided fields are changed.

path Parameters
bank_id
required
string (Bank Id)
webhook_id
required
string (Webhook Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Url (string) or Url (null) (Url)

HTTP(S) endpoint URL

Secret (string) or Secret (null) (Secret)

HMAC-SHA256 signing secret. Omit to keep existing; send null to clear.

Array of Event Types (strings) or Event Types (null) (Event Types)

List of event types

Enabled (boolean) or Enabled (null) (Enabled)

Whether this webhook is active

WebhookHttpConfig (object) or null

HTTP delivery configuration

Responses

Response Schema: application/json
id
required
string (Id)
required
Bank Id (string) or Bank Id (null) (Bank Id)
url
required
string (Url)
Secret (string) or Secret (null) (Secret)

Signing secret (redacted in responses)

event_types
required
Array of strings (Event Types)
enabled
required
boolean (Enabled)
object (WebhookHttpConfig)

HTTP delivery configuration for a webhook.

Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)

Request samples

Content type
application/json
{
  • "url": "string",
  • "secret": "string",
  • "event_types": [
    ],
  • "enabled": true,
  • "http_config": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "bank_id": "string",
  • "url": "string",
  • "secret": "string",
  • "event_types": [
    ],
  • "enabled": true,
  • "http_config": {
    },
  • "created_at": "string",
  • "updated_at": "string"
}

List webhook deliveries

Inspect delivery history for a webhook (useful for debugging).

path Parameters
bank_id
required
string (Bank Id)
webhook_id
required
string (Webhook Id)
query Parameters
limit
integer (Limit) <= 200
Default: 50

Maximum number of deliveries to return

Cursor (string) or Cursor (null) (Cursor)

Pagination cursor (created_at of last item)

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Items)
Next Cursor (string) or Next Cursor (null) (Next Cursor)

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Files

Convert files to memories

Upload files (PDF, DOCX, etc.), convert them to markdown, and retain as memories.

This endpoint handles file upload, conversion, and memory creation in a single operation.

Features:

  • Supports PDF, DOCX, PPTX, XLSX, images (parser-dependent OCR), audio (with transcription)
  • Automatic file-to-markdown conversion using pluggable parsers
  • Files stored in object storage (PostgreSQL by default, S3 for production)
  • Each file becomes a separate document with optional metadata/tags
  • Always processes asynchronously — returns operation IDs immediately

The system automatically:

  1. Stores uploaded files in object storage
  2. Converts files to markdown
  3. Creates document records with file metadata
  4. Extracts facts and creates memory units (same as regular retain)

Use the operations endpoint to monitor progress.

Request format: multipart/form-data with:

  • files: One or more files to upload
  • request: JSON string with FileRetainRequest model

Parser selection:

  • Set parser in the request body to override the server default for all files.
  • Set parser inside a files_metadata entry for per-file control.
  • Pass a list (e.g. ['iris', 'markitdown']) to define an ordered fallback chain — each parser is tried in sequence until one succeeds.
  • Falls back to the server default (HINDSIGHT_API_FILE_PARSER) if not specified.
  • Only parsers enabled on the server may be requested; others return HTTP 400.
path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: multipart/form-data
required
files
required
Array of strings <binary> (Files) [ items <binary > ]

Files to upload and convert

request
required
string (Request)

JSON string with FileRetainRequest model

Responses

Response Schema: application/json
operation_ids
required
Array of strings (Operation Ids)

Operation IDs for tracking file conversion operations. Use GET /v1/default/banks/{bank_id}/operations to list operations.

Response samples

Content type
application/json
{
  • "operation_ids": [
    ]
}

Audit

List audit logs

List audit log entries for a bank, ordered by most recent first.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Action (string) or Action (null) (Action)

Filter by action type

Transport (string) or Transport (null) (Transport)

Filter by transport (http, mcp, system)

Start Date (string) or Start Date (null) (Start Date)

Filter from this ISO datetime (inclusive)

End Date (string) or End Date (null) (End Date)

Filter until this ISO datetime (exclusive)

limit
integer (Limit) [ 1 .. 500 ]
Default: 50

Max items to return

offset
integer (Offset) >= 0
Default: 0

Offset for pagination

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
total
required
integer (Total)
limit
required
integer (Limit)
offset
required
integer (Offset)
required
Array of objects (Items)

Response samples

Content type
application/json
{
  • "bank_id": "string",
  • "total": 0,
  • "limit": 0,
  • "offset": 0,
  • "items": [
    ]
}

Audit log statistics

Get audit log counts grouped by time bucket for charting.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Action (string) or Action (null) (Action)

Filter by action type

period
string (Period)
Default: "7d"

Time period: 1d, 7d, or 30d

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
period
required
string (Period)
trunc
required
string (Trunc)
start
required
string (Start)
required
Array of objects (Buckets)

Response samples

Content type
application/json
{
  • "bank_id": "string",
  • "period": "string",
  • "trunc": "string",
  • "start": "string",
  • "buckets": [
    ]
}

LLM Traces

List LLM request traces

List traced LLM requests for a bank, ordered by most recent first. Requires LLM request tracing to be enabled (HINDSIGHT_API_LLM_TRACE_ENABLED).

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Status (string) or Status (null) (Status)

Filter by status (success, error)

Operation (string) or Operation (null) (Operation)

Filter by operation (retain, reflect, consolidation)

Scope (string) or Scope (null) (Scope)

Filter by call scope

Provider (string) or Provider (null) (Provider)

Filter by LLM provider

Trace Id (string) or Trace Id (null) (Trace Id)

Filter to one operation run (all LLM calls sharing a trace)

Document Id (string) or Document Id (null) (Document Id)

Filter to LLM calls that processed a given document

Memory Id (string) or Memory Id (null) (Memory Id)

Filter to the operation run(s) that produced or consumed a given memory_unit

group
boolean (Group)
Default: false

Paginate by operation run (trace) instead of by call; returns whole runs

Start Date (string) or Start Date (null) (Start Date)

Filter from this ISO datetime (inclusive)

End Date (string) or End Date (null) (End Date)

Filter until this ISO datetime (exclusive)

limit
integer (Limit) [ 1 .. 500 ]
Default: 50

Max items to return

offset
integer (Offset) >= 0
Default: 0

Offset for pagination

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
total
required
integer (Total)
limit
required
integer (Limit)
offset
required
integer (Offset)
required
Array of objects (Items)

Response samples

Content type
application/json
{
  • "bank_id": "string",
  • "total": 0,
  • "limit": 0,
  • "offset": 0,
  • "items": [
    ]
}

LLM request statistics

Get LLM request counts grouped by time bucket and status for charting.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Operation (string) or Operation (null) (Operation)

Filter by operation

period
string (Period)
Default: "7d"

Time period: 1d, 7d, or 30d

header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
period
required
string (Period)
trunc
required
string (Trunc)
start
required
string (Start)
required
Array of objects (Buckets)

Response samples

Content type
application/json
{
  • "bank_id": "string",
  • "period": "string",
  • "trunc": "string",
  • "start": "string",
  • "buckets": [
    ]
}