Skip to main content
API docs by Redocly

Hindsight HTTP API (0.4.17)

Download OpenAPI specification:Download

License: Apache 2.0

HTTP API for Hindsight

Monitoring

Health check endpoint

Checks the health of the API and database connection

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

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.4.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/opinion).

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Type (string) or Type (null) (Type)
limit
integer (Limit)
Default: 1000
Q (string) or Q (null) (Q)
Array of Tags (strings) or Tags (null) (Tags)
tags_match
string (Tags Match)
Default: "all_strict"
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. 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)
limit
integer (Limit)
Default: 100
offset
integer (Offset)
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
}

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

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 type parameter is optional and must be one of:

  • world: General knowledge about people, places, events, and things that happen
  • experience: Memories about experience, conversations, actions taken, and tasks performed
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 world and experience if not specified.

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')

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.

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

How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged).

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

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",
  • "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, and opinions.

This endpoint:

  1. Retrieves experience (conversations and events)
  2. Retrieves world facts relevant to the query
  3. Retrieves existing opinions (bank's 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)

Filter memories by tags during reflection. If not specified, all memories are considered.

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

How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged).

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.

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.

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.

limit
integer (Limit)
Default: 100

Maximum number of tags to return

offset
integer (Offset)
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
}

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.

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.

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, opinion) 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, opinion)

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

List all memory banks

Get a list of all agents with their profiles

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

Responses

Response Schema: application/json
required
Array of objects (Banks)
Array
bank_id
required
string (Bank Id)
Name (string) or Name (null) (Name)
required
object (DispositionTraits)

Disposition traits that influence how memories are formed and interpreted.

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

Response samples

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

Get statistics for memory bank

Get statistics about nodes and links for a specific agent

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)
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)
Last Consolidated At (string) or Last Consolidated At (null) (Last Consolidated At)

When consolidation last ran (ISO format)

pending_consolidation
integer (Pending Consolidation)
Default: 0

Number of memories not yet processed into observations

total_observations
integer (Total Observations)
Default: 0

Total number of observations

Response samples

Content type
application/json
{
  • "bank_id": "user123",
  • "failed_operations": 0,
  • "last_consolidated_at": "2024-01-15T10:30: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
}

Get memory bank profile Deprecated

Get disposition traits and mission for a memory bank. Auto-creates agent with defaults if not exists.

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 Deprecated

Update bank's disposition traits (skepticism, literalism, empathy)

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 (deprecated) Deprecated

Deprecated: Use PUT /mission instead. This endpoint now updates the mission field.

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', or 'custom'.

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)

Maximum token size for each content chunk during retain.

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.

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', or 'custom'.

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)

Maximum token size for each content chunk during retain.

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.

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
}

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.

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 fields can be overridden (LLM settings, retention parameters, etc.). Keys can be provided in Python field format (llm_provider) or environment variable format (HINDSIGHT_API_LLM_PROVIDER).

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 (llm_provider) or environment variable format (HINDSIGHT_API_LLM_PROVIDER). 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)

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

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)
Default: 100

Maximum number of entities to return

offset
integer (Offset)
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 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

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)
Array
id
required
string (Id)
bank_id
required
string (Bank Id)
name
required
string (Name)
source_query
required
string (Source Query)
content
required
string (Content)

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

tags
Array of strings (Tags)
Default: []
max_tokens
integer (Max Tokens)
Default: 2048
object (MentalModelTrigger)
Default: {}

Trigger settings for a mental model.

Last Refreshed At (string) or Last Refreshed At (null) (Last Refreshed At)
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

Response samples

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

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)
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)
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
required
string (Source Query)
content
required
string (Content)

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

tags
Array of strings (Tags)
Default: []
max_tokens
integer (Max Tokens)
Default: 2048
object (MentalModelTrigger)
Default: {}

Trigger settings for a mental model.

Last Refreshed At (string) or Last Refreshed At (null) (Last Refreshed At)
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

Response samples

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

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
required
string (Source Query)
content
required
string (Content)

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

tags
Array of strings (Tags)
Default: []
max_tokens
integer (Max Tokens)
Default: 2048
object (MentalModelTrigger)
Default: {}

Trigger settings for a mental model.

Last Refreshed At (string) or Last Refreshed At (null) (Last Refreshed At)
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

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": 2048,
  • "trigger": {
    },
  • "last_refreshed_at": "string",
  • "created_at": "string",
  • "reflect_response": { }
}

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"
}

Directives

List directives

List hard rules that are injected into prompts.

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

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)
Array
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
{
  • "items": [
    ]
}

Create directive

Create a hard rule that will be injected into 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: []

Tags for filtering

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. 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)
Default: 100
offset
integer (Offset)
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
}

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)
original_text
required
string (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)
tags
Array of strings (Tags)
Default: []

Tags associated with this document

Response samples

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

Update document

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

Tags (tags): 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.

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)

New tags for the document and its memory units. 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)

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, completed, or failed

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

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', 'completed', or 'failed'. Completed operations are removed from storage, so 'completed' means the operation finished successfully.

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
operation_id
required
string (Operation Id)
status
required
string (Status)
Enum: "pending" "completed" "failed" "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)
Result Metadata (object) or Result Metadata (null) (Result Metadata)

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

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

Child operations for batch operations (if applicable)

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_models",
  • "status": "completed",
  • "updated_at": "2024-01-15T10:31:30Z"
}

Cancel a pending async operation

Cancel a pending async operation by removing it from the queue

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
}

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. Currently supported: 'consolidation.completed'

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 all webhooks registered for a bank.

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 (Items)
Array
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)

Response samples

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

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 (with 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": [
    ]
}