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

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": "1.0.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
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.

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
  • 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: 'world', 'experience', 'mental_model'. Defaults to world and experience if not specified. Note: 'opinion' is accepted but ignored (opinions are excluded from recall).

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)

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

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. 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)
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)
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": "Based on my understanding, AI is a transformative technology...",
  • "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
}

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)

Tags applied to all items in this request. These are merged with any item-level tags.

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,
  • "document_tags": [
    ],
  • "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 mental models

total_mental_models
integer (Total Mental Models)
Default: 0

Total number of mental models

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_mental_models": 45,
  • "total_nodes": 150
}

Get memory bank profile

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

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)
DispositionTraits (object) or null
Mission (string) or Mission (null) (Mission)

The agent's mission

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

Deprecated: use mission instead

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": {
    },
  • "mission": "I am a PM helping my engineering team stay organized",
  • "name": "Alice"
}

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)
DispositionTraits (object) or null
Mission (string) or Mission (null) (Mission)

The agent's mission

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

Deprecated: use mission instead

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": {
    },
  • "mission": "I am a PM helping my engineering team stay organized",
  • "name": "Alice"
}

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 mental models

Delete all mental models 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
}

Trigger consolidation

Run memory consolidation to create/update mental models 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": [
    ]
}

Reflections

List reflections

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)
tags
Array of strings (Tags)
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 mental_models

Response samples

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

Create reflection

Create a reflection 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
name
required
string (Name)

Human-readable name for the reflection

source_query
required
string (Source Query)

The query to run to generate content

tags
Array of strings (Tags)

Tags for scoped visibility

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

Maximum tokens for generated content

Responses

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

Operation ID to track progress

Request samples

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

Response samples

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

Get reflection

Get a specific reflection by ID.

path Parameters
bank_id
required
string (Bank Id)
reflection_id
required
string (Reflection 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)
tags
Array of strings (Tags)
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 mental_models

Response samples

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

Update reflection

Update a reflection's name.

path Parameters
bank_id
required
string (Bank Id)
reflection_id
required
string (Reflection 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 reflection

Any of
string (Name)

New name for the reflection

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)
tags
Array of strings (Tags)
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 mental_models

Request samples

Content type
application/json
{
  • "name": "Updated Team Communication Preferences"
}

Response samples

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

Delete reflection

Delete a reflection.

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

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Refresh reflection

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

path Parameters
bank_id
required
string (Bank Id)
reflection_id
required
string (Reflection 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)
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)

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

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

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

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)

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
}