Skip to main content
API docs by Redocly

Hindsight HTTP API (0.1.0)

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

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

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
  • opinion: The bank's formed beliefs, perspectives, and viewpoints

Set include_entities=true to get entity observations alongside recall results.

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 (defaults to all 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)

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

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

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",
  • "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. Extracts and stores any new opinions formed
  6. Returns plain text answer, the facts used, and new opinions
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)
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.

Responses

Response Schema: application/json
text
required
string (Text)
Array of objects (Based On)
Default: []
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.

Request samples

Content type
application/json
{
  • "budget": "low",
  • "context": "This is for a research paper on AI ethics",
  • "include": {
    },
  • "max_tokens": 4096,
  • "query": "What do you think about artificial intelligence?",
  • "response_schema": {
    }
}

Response samples

Content type
application/json
{
  • "based_on": [
    ],
  • "structured_output": {
    },
  • "text": "Based on my understanding, AI is a transformative technology...",
  • "usage": {
    }
}

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)

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 and find this ID. 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.

Background (string) or Background (null) (Background)
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)

Response samples

Content type
application/json
{
  • "bank_id": "user123",
  • "failed_operations": 0,
  • "links_breakdown": {
    },
  • "links_by_fact_type": {
    },
  • "links_by_link_type": {
    },
  • "nodes_by_fact_type": {
    },
  • "pending_operations": 2,
  • "total_documents": 10,
  • "total_links": 300,
  • "total_nodes": 150
}

Get memory bank profile

Get disposition traits and background 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.

background
required
string (Background)

Response samples

Content type
application/json
{
  • "background": "I am a software engineer with 10 years of experience in startups",
  • "bank_id": "user123",
  • "disposition": {
    },
  • "name": "Alice"
}

Update memory bank disposition

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.

background
required
string (Background)

Request samples

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

Response samples

Content type
application/json
{
  • "background": "I am a software engineer with 10 years of experience in startups",
  • "bank_id": "user123",
  • "disposition": {
    },
  • "name": "Alice"
}

Add/merge memory bank background

Add new background information or merge with existing. LLM intelligently resolves conflicts, normalizes to first person, and optionally infers disposition traits.

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

If true, infer disposition traits from the merged background (default: true)

Responses

Response Schema: application/json
background
required
string (Background)
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
{
  • "background": "I was born in Texas. I am a software engineer with 10 years of experience.",
  • "disposition": {
    }
}

Create or update memory bank

Create a new agent or update existing agent with disposition and background. 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)
DispositionTraits (object) or null
Background (string) or Background (null) (Background)

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.

background
required
string (Background)

Request samples

Content type
application/json
{
  • "background": "I am a creative software engineer with 10 years of experience",
  • "disposition": {
    },
  • "name": "Alice"
}

Response samples

Content type
application/json
{
  • "background": "I am a software engineer with 10 years of experience in startups",
  • "bank_id": "user123",
  • "disposition": {
    },
  • "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
}

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

Regenerate observations for an entity based on all facts mentioning it.

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

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

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...",
  • "updated_at": "2024-01-15T10:30:00Z"
}

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 all async operations (pending and failed) for a specific agent, including error messages for failed operations

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)
required
Array of objects (Operations)

Response samples

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

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
}