Skip to main content
API docs by Redocly

Atulya HTTP API (0.8.6)

Download OpenAPI specification:Download

License: Apache 2.0

HTTP API for Atulya

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
}

Get normalized timeline data

Retrieve git-style timeline items and edges for facts, observations, and mental models.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Type (string) or Type (null) (Type)
limit
integer (Limit)
Default: 500
Q (string) or Q (null) (Q)
Array of Tags (strings) or Tags (null) (Tags)
tags_match
string (Tags Match)
Default: "all_strict"
Enum: "any" "all" "any_strict" "all_strict"
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
Array of objects (Items)
Array of objects (Edges)
total_items
required
integer (Total Items)
limit
required
integer (Limit)

Response samples

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

Get graph intelligence state graph

Retrieve a state/topic graph with high-confidence changes, contradictions, and stale signals.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
Type (string) or Type (null) (Type)
limit
integer (Limit)
Default: 18
Q (string) or Q (null) (Q)
Array of Tags (strings) or Tags (null) (Tags)
tags_match
string (Tags Match)
Default: "all_strict"
Enum: "any" "all" "any_strict" "all_strict"
confidence_min
number (Confidence Min) [ 0 .. 1 ]
Default: 0.55
node_kind
string (Node Kind)
Default: "all"
Enum: "all" "entity" "topic"
Window Days (integer) or Window Days (null) (Window Days)
Default: 90
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 (Change Events)
total_nodes
required
integer (Total Nodes)
generated_at
required
string (Generated At)
cached
boolean (Cached)
Default: false

Response samples

Content type
application/json
{
  • "nodes": [
    ],
  • "edges": [
    ],
  • "change_events": [
    ],
  • "total_nodes": 0,
  • "generated_at": "string",
  • "cached": false
}

Investigate graph intelligence

Ask a focused question over the state graph and return the relevant change events, evidence path, and checks.

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)
Type (string) or Type (null) (Type)
Array of Tags (strings) or Tags (null) (Tags)
tags_match
string (Tags Match)
Default: "all_strict"
Enum: "any" "all" "any_strict" "all_strict"
confidence_min
number (Confidence Min) [ 0 .. 1 ]
Default: 0.55
node_kind
string (Node Kind)
Default: "all"
Enum: "all" "entity" "topic"
Window Days (integer) or Window Days (null) (Window Days)
Default: 90
limit
integer (Limit) [ 1 .. 100 ]
Default: 18

Responses

Response Schema: application/json
answer
required
string (Answer)
focal_node_ids
Array of strings (Focal Node Ids)
focal_edge_ids
Array of strings (Focal Edge Ids)
Array of objects (Change Events)
Array of objects (Evidence Path)
recommended_checks
Array of strings (Recommended Checks)

Request samples

Content type
application/json
{
  • "query": "string",
  • "type": "string",
  • "tags": [
    ],
  • "tags_match": "any",
  • "confidence_min": 0.55,
  • "node_kind": "all",
  • "window_days": 90,
  • "limit": 18
}

Response samples

Content type
application/json
{
  • "answer": "string",
  • "focal_node_ids": [
    ],
  • "focal_edge_ids": [
    ],
  • "change_events": [
    ],
  • "evidence_path": [
    ],
  • "recommended_checks": [
    ]
}

Get anomaly intelligence for bank

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
limit
integer (Limit) [ 1 .. 200 ]
Default: 50
Status (string) or Status (null) (Status)
Array of Anomaly Types (strings) or Anomaly Types (null) (Anomaly Types)
min_severity
number (Min Severity) [ 0 .. 1 ]
Default: 0

Responses

Response Schema: application/json
required
object (AnomalyIntelligenceSummaryResponse)
Array of objects (Events)
total_events_in_response
required
integer (Total Events In Response)

Request samples

Content type
application/json
{
  • "limit": 50,
  • "status": "open",
  • "anomaly_types": [
    ],
  • "min_severity": 0
}

Response samples

Content type
application/json
{
  • "summary": {
    },
  • "events": [
    ],
  • "total_events_in_response": 0
}

Get scalable graph summary

Retrieve a clustered graph summary and top-use nodes for scalable graph exploration.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
surface
string (Surface)
Default: "state"
Enum: "state" "evidence"
Type (string) or Type (null) (Type)
Q (string) or Q (null) (Q)
Array of Tags (strings) or Tags (null) (Tags)
tags_match
string (Tags Match)
Default: "all_strict"
Enum: "any" "all" "any_strict" "all_strict"
confidence_min
number (Confidence Min) [ 0 .. 1 ]
Default: 0.55
node_kind
string (Node Kind)
Default: "all"
Enum: "all" "entity" "topic"
Window Days (integer) or Window Days (null) (Window Days)
Default: 90
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
surface
required
string (Surface)
Enum: "state" "evidence"
mode_hint
required
string (Mode Hint)
Enum: "detail" "compact" "overview"
total_nodes
required
integer (Total Nodes)
total_edges
required
integer (Total Edges)
Array of objects (Clusters)
Array of objects (Top Nodes)
Array of objects (Bundled Edges)
initial_focus_ids
Array of strings (Initial Focus Ids)
generated_at
required
string (Generated At)
cached
boolean (Cached)
Default: false

Response samples

Content type
application/json
{
  • "surface": "state",
  • "mode_hint": "detail",
  • "total_nodes": 0,
  • "total_edges": 0,
  • "clusters": [
    ],
  • "top_nodes": [
    ],
  • "bundled_edges": [
    ],
  • "initial_focus_ids": [
    ],
  • "generated_at": "string",
  • "cached": false
}

Get focused graph neighborhood

Retrieve a bounded neighborhood for focused graph exploration and detail rendering.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
surface
string (Surface)
Default: "state"
Enum: "state" "evidence"
Type (string) or Type (null) (Type)
Q (string) or Q (null) (Q)
Array of Tags (strings) or Tags (null) (Tags)
tags_match
string (Tags Match)
Default: "all_strict"
Enum: "any" "all" "any_strict" "all_strict"
confidence_min
number (Confidence Min) [ 0 .. 1 ]
Default: 0.55
node_kind
string (Node Kind)
Default: "all"
Enum: "all" "entity" "topic"
Window Days (integer) or Window Days (null) (Window Days)
Default: 90
Array of Focus Ids (strings) or Focus Ids (null) (Focus Ids)
depth
integer (Depth) [ 1 .. 3 ]
Default: 1
limit_nodes
integer (Limit Nodes) [ 1 .. 120 ]
Default: 60
limit_edges
integer (Limit Edges) [ 1 .. 300 ]
Default: 140
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
surface
required
string (Surface)
Enum: "state" "evidence"
mode_hint
required
string (Mode Hint)
Enum: "detail" "compact" "overview"
focus_ids
Array of strings (Focus Ids)
Array of objects (Nodes)
Array of objects (Edges)
total_nodes
required
integer (Total Nodes)
total_edges
required
integer (Total Edges)
has_more
boolean (Has More)
Default: false
Cursor (string) or Cursor (null) (Cursor)
generated_at
required
string (Generated At)
cached
boolean (Cached)
Default: false

Response samples

Content type
application/json
{
  • "surface": "state",
  • "mode_hint": "detail",
  • "focus_ids": [
    ],
  • "nodes": [
    ],
  • "edges": [
    ],
  • "total_nodes": 0,
  • "total_edges": 0,
  • "has_more": false,
  • "cursor": "string",
  • "generated_at": "string",
  • "cached": false
}

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)
Branch Name (string) or Branch Name (null) (Branch Name)
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)
query Parameters
Branch Name (string) or Branch Name (null) (Branch Name)
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)
Branch Name (string) or Branch Name (null) (Branch Name)

Optional memory repo branch to query without checking it out.

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

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

Compound boolean tag predicates. Each entry is a leaf ({"tags": [...], "match": "any|all|any_strict|all_strict"}) or a nested group ({"and": [...]}, {"or": [...]}, {"not": {...}}). Top-level entries are AND-ed together. Mutually exclusive with tags.

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

Optional memory repo branch to query without checking it out.

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

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

Compound boolean tag predicates. Each entry is a leaf ({"tags": [...], "match": "any|all|any_strict|all_strict"}) or a nested group ({"and": [...]}, {"or": [...]}, {"not": {...}}). Top-level entries are AND-ed together. Mutually exclusive with tags.

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

Internet research (live web)

Run the internet research agent: SearXNG search and optional Firecrawl extract. Uses the same LLM configuration as reflect for this bank. Does not read or write memories.

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)

Question to answer using the public web only

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

Budget levels for recall/reflect operations.

max_tokens
integer (Max Tokens)
Default: 4096

Max completion tokens for each LLM step where supported

object (ReflectIncludeOptions)

Optional tool trace (include.facts is ignored).

Responses

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

Markdown answer synthesized from web tools

source_urls
Array of strings (Source Urls)

URLs the model relied on

writes_to_bank
boolean (Writes To Bank)
Default: false

Always false; included so clients can assert no graph mutation occurred

TokenUsage (object) or null

LLM token usage for this run

ReflectTrace (object) or null

Tool and LLM trace when include.tool_calls was set

Request samples

Content type
application/json
{
  • "budget": "mid",
  • "include": {
    },
  • "max_tokens": 4096,
  • "query": "Latest stable release of Python"
}

Response samples

Content type
application/json
{
  • "text": "string",
  • "source_urls": [
    ],
  • "writes_to_bank": false,
  • "usage": {
    },
  • "trace": {
    }
}

Submit async reflect

Queue a reflect operation for background execution and retrieve the result via the operations API.

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

Optional memory repo branch to query without checking it out.

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

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

Compound boolean tag predicates. Each entry is a leaf ({"tags": [...], "match": "any|all|any_strict|all_strict"}) or a nested group ({"and": [...]}, {"or": [...]}, {"not": {...}}). Top-level entries are AND-ed together. Mutually exclusive with tags.

Responses

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

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
{
  • "operation_id": "550e8400-e29b-41d4-a716-446655440000",
  • "status": "queued"
}

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.

Bank Preset (string) or Bank Preset (null) (Bank Preset)

Optional starter kit merged before explicit fields: 'codebase' tunes retain/reflect/observations for repository and ASD chunk ingest, and idempotently seeds developer-guide mental models plus one evidence-first directive. Unknown values are ignored.

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.

Bank Preset (string) or Bank Preset (null) (Bank Preset)

Optional starter kit merged before explicit fields: 'codebase' tunes retain/reflect/observations for repository and ASD chunk ingest, and idempotently seeds developer-guide mental models plus one evidence-first directive. Unknown values are ignored.

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

Trigger sub_routine

Queue a sub_routine operation for atulya-brain cache refresh and activity-time learning.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
mode
string (Mode)
Default: "incremental"
Enum: "warmup" "incremental" "full_copy"
horizon_hours
integer (Horizon Hours) [ 1 .. 168 ]
Default: 24
force_rebuild
boolean (Force Rebuild)
Default: false

Responses

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

ID of the async consolidation operation

deduplicated
boolean (Deduplicated)
Default: false

True if an existing pending task was reused

Request samples

Content type
application/json
{
  • "mode": "warmup",
  • "horizon_hours": 24,
  • "force_rebuild": false
}

Response samples

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

Trigger Dream/Trance generation

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
trigger_source
string (Trigger Source)
Default: "manual"

manual | event | cron

run_type
string (Run Type)
Default: "dream"

dream | trance

Responses

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

ID of the async consolidation operation

deduplicated
boolean (Deduplicated)
Default: false

True if an existing pending task was reused

Request samples

Content type
application/json
{
  • "trigger_source": "manual",
  • "run_type": "dream"
}

Response samples

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

List dream artifacts

path Parameters
bank_id
required
string (Bank Id)
query Parameters
limit
integer (Limit) [ 1 .. 100 ]
Default: 20
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Items)
Array
run_id
required
string (Run Id)
bank_id
required
string (Bank Id)
status
required
string (Status)
run_type
required
string (Run Type)
trigger_source
required
string (Trigger Source)
created_at
required
string (Created At)
Updated At (string) or Updated At (null) (Updated At)
Narrative Html (string) or Narrative Html (null) (Narrative Html)
Summary (string) or Summary (null) (Summary)
object (Evidence Basis)
object (Signals)
Array of objects (Predictions)
Array of objects (Growth Hypotheses)
Array of objects (Promotion Proposals)
Array of objects (Validation Outcomes)
object (Confidence)
novelty_score
number (Novelty Score)
Default: 0
maturity_tier
string (Maturity Tier)
Default: "sparse"
Failure Reason (string) or Failure Reason (null) (Failure Reason)
quality_score
number (Quality Score)
Default: 0
legacy_run
boolean (Legacy Run)
Default: false
Source Artifact Id (string) or Source Artifact Id (null) (Source Artifact Id)

Response samples

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

Review a dream proposal

path Parameters
bank_id
required
string (Bank Id)
proposal_id
required
string (Proposal Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
action
required
string (Action)
Enum: "approve" "reject" "request_more_evidence"
Note (string) or Note (null) (Note)

Responses

Response Schema: application/json
any

Request samples

Content type
application/json
{
  • "action": "approve",
  • "note": "string"
}

Response samples

Content type
application/json
null

Update dream prediction outcome

path Parameters
bank_id
required
string (Bank Id)
prediction_id
required
string (Prediction Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
status
required
string (Status)
Enum: "confirmed" "contradicted" "request_more_evidence"
Note (string) or Note (null) (Note)
evidence_ids
Array of strings (Evidence Ids)

Responses

Response Schema: application/json
any

Request samples

Content type
application/json
{
  • "status": "confirmed",
  • "note": "string",
  • "evidence_ids": [
    ]
}

Response samples

Content type
application/json
null

Get dream generation stats

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_runs
required
integer (Total Runs)
required
Last Run At (string) or Last Run At (null) (Last Run At)
avg_quality
required
number (Avg Quality)
avg_tokens
required
number (Avg Tokens)
avg_output_tokens
required
number (Avg Output Tokens)
distillation_pass_rate
required
number (Distillation Pass Rate)
distilled_count
required
integer (Distilled Count)
validation_rate
number (Validation Rate)
Default: 0
avg_novelty
number (Avg Novelty)
Default: 0
failed_run_count
integer (Failed Run Count)
Default: 0
duplicate_suppression_count
integer (Duplicate Suppression Count)
Default: 0
prediction_confirmation_rate
number (Prediction Confirmation Rate)
Default: 0
unresolved_prediction_backlog
integer (Unresolved Prediction Backlog)
Default: 0

Response samples

Content type
application/json
{
  • "bank_id": "string",
  • "total_runs": 0,
  • "last_run_at": "string",
  • "avg_quality": 0,
  • "avg_tokens": 0,
  • "avg_output_tokens": 0,
  • "distillation_pass_rate": 0,
  • "distilled_count": 0,
  • "validation_rate": 0,
  • "avg_novelty": 0,
  • "failed_run_count": 0,
  • "duplicate_suppression_count": 0,
  • "prediction_confirmation_rate": 0,
  • "unresolved_prediction_backlog": 0
}

Get brain runtime status

Return current brain cache state for the bank.

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

Responses

Response Schema: application/json
enabled
required
boolean (Enabled)
circuit_open
required
boolean (Circuit Open)
failure_count
required
integer (Failure Count)
bank_id
required
string (Bank Id)
file_path
required
string (File Path)
exists
required
boolean (Exists)
size_bytes
required
integer (Size Bytes)
Last Modified At (string) or Last Modified At (null) (Last Modified At)
Source Snapshot Id (string) or Source Snapshot Id (null) (Source Snapshot Id)
Generated At (string) or Generated At (null) (Generated At)
native_library_loaded
required
boolean (Native Library Loaded)
Format Version (integer) or Format Version (null) (Format Version)
Model Signature (string) or Model Signature (null) (Model Signature)
Compatibility Reason (string) or Compatibility Reason (null) (Compatibility Reason)
object (Metrics)

Response samples

Content type
application/json
{
  • "enabled": true,
  • "circuit_open": true,
  • "failure_count": 0,
  • "bank_id": "string",
  • "file_path": "string",
  • "exists": true,
  • "size_bytes": 0,
  • "last_modified_at": "string",
  • "source_snapshot_id": "string",
  • "generated_at": "string",
  • "native_library_loaded": true,
  • "format_version": 0,
  • "model_signature": "string",
  • "compatibility_reason": "string",
  • "metrics": {
    }
}

Get activity-time predictions

Return model predictions for likely active hours for this bank.

path Parameters
bank_id
required
string (Bank Id)
query Parameters
horizon_hours
integer (Horizon Hours) [ 1 .. 168 ]
Default: 24
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
horizon_hours
required
integer (Horizon Hours)
required
Array of objects (Predictions)
sample_count
integer (Sample Count)
Default: 0
Source Snapshot Id (string) or Source Snapshot Id (null) (Source Snapshot Id)
Model Signature (string) or Model Signature (null) (Model Signature)

Response samples

Content type
application/json
{
  • "bank_id": "string",
  • "horizon_hours": 0,
  • "predictions": [
    ],
  • "sample_count": 0,
  • "source_snapshot_id": "string",
  • "model_signature": "string"
}

Get full activity histogram

Return all 24 hourly activity probabilities from the current sub_routine model.

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 (Histogram)
sample_count
integer (Sample Count)
Default: 0
Source Snapshot Id (string) or Source Snapshot Id (null) (Source Snapshot Id)
Model Signature (string) or Model Signature (null) (Model Signature)

Response samples

Content type
application/json
{
  • "bank_id": "string",
  • "histogram": [
    ],
  • "sample_count": 0,
  • "source_snapshot_id": "string",
  • "model_signature": "string"
}

Get brain influence analytics

path Parameters
bank_id
required
string (Bank Id)
query Parameters
window_days
integer (Window Days) [ 1 .. 90 ]
Default: 14
top_k
integer (Top K) [ 5 .. 50 ]
Default: 12
entity_type
string (Entity Type)
Default: "all"
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
window_days
required
integer (Window Days)
entity_type
required
string (Entity Type)
required
Array of objects (Leaderboard)
required
Array of objects (Heatmap)
required
Array of objects (Trend)
required
Array of objects (Anomalies)
required
object (Summary)

Response samples

Content type
application/json
{
  • "bank_id": "string",
  • "window_days": 0,
  • "entity_type": "string",
  • "leaderboard": [
    ],
  • "heatmap": [
    ],
  • "trend": [
    ],
  • "anomalies": [
    ],
  • "summary": { }
}

Export current .brain snapshot

Export validated brain snapshot for this bank.

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

Responses

Response Schema: application/json
any

Response samples

Content type
application/json
null

Validate .brain import payload

Validate schema/version/checksum compatibility before importing.

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

Brain snapshot payload

Responses

Response Schema: application/json
valid
required
boolean (Valid)
Version (integer) or Version (null) (Version)
Reason (string) or Reason (null) (Reason)

Response samples

Content type
application/json
{
  • "valid": true,
  • "version": 0,
  • "reason": "string"
}

Import .brain snapshot

Import a validated brain snapshot into this bank cache path.

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

Brain snapshot payload

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
file_path
required
string (File Path)
size_bytes
required
integer (Size Bytes)
Format Version (integer) or Format Version (null) (Format Version)

Response samples

Content type
application/json
{
  • "bank_id": "string",
  • "file_path": "string",
  • "size_bytes": 0,
  • "format_version": 0
}

Learn from a remote brain

Connect to another Atulya instance and distill its knowledge into this bank's brain.

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

URL of the remote Atulya API (e.g. http://host:8888)

remote_bank_id
required
string (Remote Bank Id)

Bank ID on the remote instance to learn from

remote_api_key
string (Remote Api Key)
Default: ""

Optional API key for the remote instance

learning_type
string (Learning Type)
Default: "auto"
Enum: "auto" "distilled" "structured" "raw_mirror"
mode
string (Mode)
Default: "incremental"
Enum: "incremental" "full_copy"
horizon_hours
integer (Horizon Hours) [ 1 .. 168 ]
Default: 24

Responses

Response Schema: application/json
operation_id
required
string (Operation Id)
deduplicated
boolean (Deduplicated)
Default: false

Request samples

Content type
application/json
{
  • "remote_endpoint": "string",
  • "remote_bank_id": "string",
  • "remote_api_key": "",
  • "learning_type": "auto",
  • "mode": "incremental",
  • "horizon_hours": 24
}

Response samples

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

Memory Repos

Create a memory repo

Create an opt-in git-like memory repo rooted at a bank, optionally cloning from another bank first.

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

Root bank ID that will become the repo working tree

Repo Name (string) or Repo Name (null) (Repo Name)

Optional display name for the repo

Source Bank Id (string) or Source Bank Id (null) (Source Bank Id)

Optional source bank to clone into the root bank

Responses

Response Schema: application/json
repo_id
required
string (Repo Id)
root_bank_id
required
string (Root Bank Id)
name
required
string (Name)
active_branch
required
string (Active Branch)
Head Commit Id (string) or Head Commit Id (null) (Head Commit Id)
Head Message (string) or Head Message (null) (Head Message)
Head Created At (string) or Head Created At (null) (Head Created At)
Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)
Array of Branches (objects) or Branches (null) (Branches)

Request samples

Content type
application/json
{
  • "bank_id": "string",
  • "repo_name": "string",
  • "source_bank_id": "string"
}

Response samples

Content type
application/json
{
  • "repo_id": "string",
  • "root_bank_id": "string",
  • "name": "string",
  • "active_branch": "string",
  • "head_commit_id": "string",
  • "head_message": "string",
  • "head_created_at": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "branches": [
    ]
}

List memory repos

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

Responses

Response Schema: application/json
required
Array of objects (Repos)
Array
repo_id
required
string (Repo Id)
root_bank_id
required
string (Root Bank Id)
name
required
string (Name)
active_branch
required
string (Active Branch)
Head Commit Id (string) or Head Commit Id (null) (Head Commit Id)
Head Message (string) or Head Message (null) (Head Message)
Head Created At (string) or Head Created At (null) (Head Created At)
Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)
Array of Branches (objects) or Branches (null) (Branches)

Response samples

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

Get memory repo for a bank

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

Responses

Response Schema: application/json
MemoryRepoSummaryResponse (object) or null
Any of
repo_id
required
string (Repo Id)
root_bank_id
required
string (Root Bank Id)
name
required
string (Name)
active_branch
required
string (Active Branch)
Head Commit Id (string) or Head Commit Id (null) (Head Commit Id)
Head Message (string) or Head Message (null) (Head Message)
Head Created At (string) or Head Created At (null) (Head Created At)
Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)
Array of Branches (objects) or Branches (null) (Branches)

Response samples

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

Get memory repo summary

path Parameters
repo_id
required
string (Repo Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
repo_id
required
string (Repo Id)
root_bank_id
required
string (Root Bank Id)
name
required
string (Name)
active_branch
required
string (Active Branch)
Head Commit Id (string) or Head Commit Id (null) (Head Commit Id)
Head Message (string) or Head Message (null) (Head Message)
Head Created At (string) or Head Created At (null) (Head Created At)
Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)
Array of Branches (objects) or Branches (null) (Branches)

Response samples

Content type
application/json
{
  • "repo_id": "string",
  • "root_bank_id": "string",
  • "name": "string",
  • "active_branch": "string",
  • "head_commit_id": "string",
  • "head_message": "string",
  • "head_created_at": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "branches": [
    ]
}

Enable repo mode on a bank

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

Optional display name for the repo

Any of
string (Repo Name)

Optional display name for the repo

Responses

Response Schema: application/json
repo_id
required
string (Repo Id)
root_bank_id
required
string (Root Bank Id)
name
required
string (Name)
active_branch
required
string (Active Branch)
Head Commit Id (string) or Head Commit Id (null) (Head Commit Id)
Head Message (string) or Head Message (null) (Head Message)
Head Created At (string) or Head Created At (null) (Head Created At)
Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)
Array of Branches (objects) or Branches (null) (Branches)

Request samples

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

Response samples

Content type
application/json
{
  • "repo_id": "string",
  • "root_bank_id": "string",
  • "name": "string",
  • "active_branch": "string",
  • "head_commit_id": "string",
  • "head_message": "string",
  • "head_created_at": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "branches": [
    ]
}

List memory repo branches 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 (Branches)
Array
property name*
additional property
any

Response samples

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

List memory repo branches

path Parameters
repo_id
required
string (Repo Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Branches)
Array
property name*
additional property
any

Response samples

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

Create memory repo branch

path Parameters
repo_id
required
string (Repo Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
branch_name
required
string (Branch Name)

Branch name to create

From Commit Id (string) or From Commit Id (null) (From Commit Id)

Optional commit to branch from

Responses

Response Schema: application/json
property name*
additional property
any

Request samples

Content type
application/json
{
  • "branch_name": "string",
  • "from_commit_id": "string"
}

Response samples

Content type
application/json
{ }

Checkout memory repo branch

path Parameters
repo_id
required
string (Repo Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
branch_name
required
string (Branch Name)

Branch to checkout

Responses

Response Schema: application/json
repo_id
required
string (Repo Id)
root_bank_id
required
string (Root Bank Id)
name
required
string (Name)
active_branch
required
string (Active Branch)
Head Commit Id (string) or Head Commit Id (null) (Head Commit Id)
Head Message (string) or Head Message (null) (Head Message)
Head Created At (string) or Head Created At (null) (Head Created At)
Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)
Array of Branches (objects) or Branches (null) (Branches)

Request samples

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

Response samples

Content type
application/json
{
  • "repo_id": "string",
  • "root_bank_id": "string",
  • "name": "string",
  • "active_branch": "string",
  • "head_commit_id": "string",
  • "head_message": "string",
  • "head_created_at": "string",
  • "created_at": "string",
  • "updated_at": "string",
  • "branches": [
    ]
}

Fork a memory repo version into a new bank

path Parameters
repo_id
required
string (Repo Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
target_bank_id
required
string (Target Bank Id)

Brand-new bank ID that will receive the forked snapshot

Target Bank Name (string) or Target Bank Name (null) (Target Bank Name)

Optional display name for the new bank

Source Branch (string) or Source Branch (null) (Source Branch)

Optional source branch to fork from. Defaults to the repo's active branch.

Source Commit Id (string) or Source Commit Id (null) (Source Commit Id)

Optional source commit to fork from. Mutually exclusive with source_branch.

include_workspace
boolean (Include Workspace)
Default: false

When true, fork the live branch workspace instead of the branch HEAD commit.

enable_repo
boolean (Enable Repo)
Default: false

Enable repo mode on the forked bank after materializing the snapshot.

Repo Name (string) or Repo Name (null) (Repo Name)

Optional repo display name for the forked bank when enable_repo=true.

Responses

Response Schema: application/json
bank_id
required
string (Bank Id)
Bank Name (string) or Bank Name (null) (Bank Name)
source_repo_id
required
string (Source Repo Id)
source_ref
required
string (Source Ref)
Source Branch (string) or Source Branch (null) (Source Branch)
Source Commit Id (string) or Source Commit Id (null) (Source Commit Id)
include_workspace
required
boolean (Include Workspace)
repo_enabled
required
boolean (Repo Enabled)
MemoryRepoSummaryResponse (object) or null

Request samples

Content type
application/json
{
  • "target_bank_id": "string",
  • "target_bank_name": "string",
  • "source_branch": "string",
  • "source_commit_id": "string",
  • "include_workspace": false,
  • "enable_repo": false,
  • "repo_name": "string"
}

Response samples

Content type
application/json
{
  • "bank_id": "string",
  • "bank_name": "string",
  • "source_repo_id": "string",
  • "source_ref": "string",
  • "source_branch": "string",
  • "source_commit_id": "string",
  • "include_workspace": true,
  • "repo_enabled": true,
  • "repo": {
    }
}

Commit active memory repo workspace

path Parameters
repo_id
required
string (Repo Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
message
required
string (Message)

Commit message

Actor (string) or Actor (null) (Actor)

Optional actor label

Responses

Response Schema: application/json
property name*
additional property
any

Request samples

Content type
application/json
{
  • "message": "string",
  • "actor": "string"
}

Response samples

Content type
application/json
{ }

Get memory repo status

path Parameters
repo_id
required
string (Repo Id)
query Parameters
Branch Name (string) or Branch Name (null) (Branch Name)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
repo_id
required
string (Repo Id)
branch_name
required
string (Branch Name)
workspace_bank_id
required
string (Workspace Bank Id)
Head Commit Id (string) or Head Commit Id (null) (Head Commit Id)
dirty
required
boolean (Dirty)
changed_components
required
Array of strings (Changed Components)
required
object (Table Deltas)

Response samples

Content type
application/json
{
  • "repo_id": "string",
  • "branch_name": "string",
  • "workspace_bank_id": "string",
  • "head_commit_id": "string",
  • "dirty": true,
  • "changed_components": [
    ],
  • "table_deltas": {
    }
}

Get memory repo commit log

path Parameters
repo_id
required
string (Repo Id)
query Parameters
Branch Name (string) or Branch Name (null) (Branch Name)
limit
integer (Limit)
Default: 50
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
required
Array of objects (Commits)
Array
property name*
additional property
any

Response samples

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

Diff memory repo commits, branches, or workspace

path Parameters
repo_id
required
string (Repo Id)
query Parameters
From Commit Id (string) or From Commit Id (null) (From Commit Id)
To Commit Id (string) or To Commit Id (null) (To Commit Id)
From Branch (string) or From Branch (null) (From Branch)
To Branch (string) or To Branch (null) (To Branch)
include_workspace
boolean (Include Workspace)
Default: false
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
repo_id
required
string (Repo Id)
from_ref
required
string (From Ref)
to_ref
required
string (To Ref)
dirty
required
boolean (Dirty)
changed_components
required
Array of strings (Changed Components)
required
object (Table Deltas)

Response samples

Content type
application/json
{
  • "repo_id": "string",
  • "from_ref": "string",
  • "to_ref": "string",
  • "dirty": true,
  • "changed_components": [
    ],
  • "table_deltas": {
    }
}

Reset active memory repo branch hard

path Parameters
repo_id
required
string (Repo Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
commit_id
required
string (Commit Id)

Commit to reset the active branch to

force
boolean (Force)
Default: false

Allow reset even when the workspace is dirty

Responses

Response Schema: application/json
repo_id
required
string (Repo Id)
branch_name
required
string (Branch Name)
workspace_bank_id
required
string (Workspace Bank Id)
Head Commit Id (string) or Head Commit Id (null) (Head Commit Id)
dirty
required
boolean (Dirty)
changed_components
required
Array of strings (Changed Components)
required
object (Table Deltas)

Request samples

Content type
application/json
{
  • "commit_id": "string",
  • "force": false
}

Response samples

Content type
application/json
{
  • "repo_id": "string",
  • "branch_name": "string",
  • "workspace_bank_id": "string",
  • "head_commit_id": "string",
  • "dirty": true,
  • "changed_components": [
    ],
  • "table_deltas": {
    }
}

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

Get entity trajectory

Return the latest LLM+HMM-style progression snapshot for an entity, if computed.

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
entity_id
required
string (Entity Id)
bank_id
required
string (Bank Id)
Computed At (string) or Computed At (null) (Computed At)
state_vocabulary
required
Array of strings (State Vocabulary)
vocabulary_hash
string (Vocabulary Hash)
Default: ""
transition_matrix
required
Array of numbers (Transition Matrix) [ items ]
current_state
required
string (Current State)
required
Array of objects (Viterbi Path)
forecast_horizon
required
integer (Forecast Horizon)
required
object (Forecast Distribution)
Forward Log Prob (number) or Forward Log Prob (null) (Forward Log Prob)
Anomaly Score (number) or Anomaly Score (null) (Anomaly Score)
llm_model
string (Llm Model)
Default: ""
prompt_version
string (Prompt Version)
Default: ""

Response samples

Content type
application/json
{
  • "entity_id": "string",
  • "bank_id": "string",
  • "computed_at": "string",
  • "state_vocabulary": [
    ],
  • "vocabulary_hash": "",
  • "transition_matrix": [
    ],
  • "current_state": "string",
  • "viterbi_path": [
    ],
  • "forecast_horizon": 0,
  • "forecast_distribution": {
    },
  • "forward_log_prob": 0,
  • "anomaly_score": 0,
  • "llm_model": "",
  • "prompt_version": ""
}

Queue entity trajectory recompute

Enqueue a background job to recompute the trajectory for this entity.

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
operation_id
required
string (Operation Id)
status
string (Status)
Default: "pending"

Response samples

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

Get entity intelligence

Return the latest bank-level entity intelligence snapshot, if computed.

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)
Computed At (string) or Computed At (null) (Computed At)
entity_count
required
integer (Entity Count)
source_entity_count
required
integer (Source Entity Count)
entity_snapshot_hash
string (Entity Snapshot Hash)
Default: ""
content
required
string (Content)
object (Structured Content)
Default: {}
object (Entity Context)
Default: {}
object (Delta Metadata)
Default: {}
llm_model
string (Llm Model)
Default: ""
prompt_version
string (Prompt Version)
Default: ""

Response samples

Content type
application/json
{
  • "bank_id": "string",
  • "computed_at": "string",
  • "entity_count": 0,
  • "source_entity_count": 0,
  • "entity_snapshot_hash": "",
  • "content": "string",
  • "structured_content": { },
  • "entity_context": { },
  • "delta_metadata": { },
  • "llm_model": "",
  • "prompt_version": ""
}

Queue entity intelligence recompute

Enqueue a background job to recompute bank-level entity intelligence.

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)
status
string (Status)
Default: "pending"

Response samples

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

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

Branch Name (string) or Branch Name (null) (Branch Name)

Optional memory repo branch to inspect without checking it out.

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)
query Parameters
Branch Name (string) or Branch Name (null) (Branch Name)
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"
}

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, reflect, consolidation, refresh_mental_model, file_convert_retain, codebase_import, codebase_refresh, codebase_approve, 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)
Queue State (string) or Queue State (null) (Queue State)
Stage (string) or Stage (null) (Stage)

High-level progress stage for pending async work, derived from result_metadata.operation_stage.

OperationProgressResponse (object) or null

Typed progress counters when the operation exposes known totals.

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
}

Get operation result

Get the final user-facing result payload for an async operation.

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)
Queue State (string) or Queue State (null) (Queue State)
Stage (string) or Stage (null) (Stage)
OperationProgressResponse (object) or null
Result Metadata (object) or Result Metadata (null) (Result Metadata)
ReflectResponse (object) or Result (object) or Result (null) (Result)

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": "reflect",
  • "result": {
    },
  • "stage": "persisting_result",
  • "status": "completed",
  • "updated_at": "2024-01-15T10:31:30Z"
}

Retry a failed async operation

Create a new pending operation by re-queueing a failed async operation using its original task payload.

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)
retried_from_operation_id
required
string (Retried From Operation Id)
bank_id
required
string (Bank Id)
Operation Type (string) or Operation Type (null) (Operation Type)

Response samples

Content type
application/json
{
  • "bank_id": "user123",
  • "message": "Retried operation 550e8400-e29b-41d4-a716-446655440000 as 0196e188-6db5-7f2a-a5f8-f654d2fcb3ad",
  • "operation_id": "0196e188-6db5-7f2a-a5f8-f654d2fcb3ad",
  • "operation_type": "consolidation",
  • "retried_from_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 (ATULYA_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": [
    ]
}

Codebases

Import a codebase from ZIP

Upload a repository ZIP archive and build a deterministic codebase snapshot without cloning or LLM indexing.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: multipart/form-data
required
archive
required
string <binary> (Archive)

Repository ZIP archive

request
required
string (Request)

JSON string with CodebaseImportZipRequest model

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
snapshot_id
required
string (Snapshot Id)
operation_id
required
string (Operation Id)
status
required
string (Status)

Response samples

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

Import a single source file as a codebase

Upload one source file and run the full ASD parse → chunk → code-intel → review pipeline on it. Useful for self-contained scripts, single-file applications, or files too granular for a full ZIP import. virtual_path controls the logical path recorded in the snapshot (defaults to the uploaded filename).

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

Source file to import

request
required
string (Request)

JSON string with CodebaseImportFileRequest model

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
snapshot_id
required
string (Snapshot Id)
operation_id
required
string (Operation Id)
status
required
string (Status)
filename
required
string (Filename)
virtual_path
required
string (Virtual Path)

Response samples

Content type
application/json
{
  • "codebase_id": "string",
  • "snapshot_id": "string",
  • "operation_id": "string",
  • "status": "string",
  • "filename": "string",
  • "virtual_path": "string"
}

Import a public GitHub codebase

Resolve a public GitHub ref, download its archive, and build a deterministic codebase snapshot.

path Parameters
bank_id
required
string (Bank Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Owner (string) or Owner (null) (Owner)
Repo (string) or Repo (null) (Repo)
Ref (string) or Ref (null) (Ref)
Repo Url (string) or Repo Url (null) (Repo Url)
Root Path (string) or Root Path (null) (Root Path)
include_globs
Array of strings (Include Globs)
Default: []
exclude_globs
Array of strings (Exclude Globs)
Default: []
refresh_existing
boolean (Refresh Existing)
Default: false

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
snapshot_id
required
string (Snapshot Id)
operation_id
required
string (Operation Id)
status
required
string (Status)
resolved_commit_sha
required
string (Resolved Commit Sha)

Request samples

Content type
application/json
{
  • "owner": "string",
  • "repo": "string",
  • "ref": "string",
  • "repo_url": "string",
  • "root_path": "string",
  • "include_globs": [ ],
  • "exclude_globs": [ ],
  • "refresh_existing": false
}

Response samples

Content type
application/json
{
  • "codebase_id": "string",
  • "snapshot_id": "string",
  • "operation_id": "string",
  • "status": "string",
  • "resolved_commit_sha": "string"
}

Refresh a codebase snapshot

Refresh a GitHub-backed codebase by resolving the latest commit SHA and rebuilding a new reviewable ASD snapshot.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Ref (string) or Ref (null) (Ref)
full_rebuild
boolean (Full Rebuild)
Default: false

Responses

Response Schema: application/json
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
Operation Id (string) or Operation Id (null) (Operation Id)
status
required
string (Status)
changed_files
integer (Changed Files)
Default: 0
added_files
integer (Added Files)
Default: 0
deleted_files
integer (Deleted Files)
Default: 0
noop
boolean (Noop)
Default: false

Request samples

Content type
application/json
{
  • "ref": "string",
  • "full_rebuild": false
}

Response samples

Content type
application/json
{
  • "snapshot_id": "string",
  • "operation_id": "string",
  • "status": "string",
  • "changed_files": 0,
  • "added_files": 0,
  • "deleted_files": 0,
  • "noop": false
}

Approve a codebase snapshot for memory hydration

Explicitly approve the current or selected reviewable codebase snapshot so Atulya can hydrate source-file text into memory.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
memory_ingest_mode
string (Memory Ingest Mode)
Default: "direct"
Enum: "direct" "retain"

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
snapshot_id
required
string (Snapshot Id)
operation_id
required
string (Operation Id)
status
required
string (Status)
memory_ingest_mode
string (Memory Ingest Mode)
Default: "direct"
Enum: "direct" "retain"

Request samples

Content type
application/json
{
  • "snapshot_id": "string",
  • "memory_ingest_mode": "direct"
}

Response samples

Content type
application/json
{
  • "codebase_id": "string",
  • "snapshot_id": "string",
  • "operation_id": "string",
  • "status": "string",
  • "memory_ingest_mode": "direct"
}

List codebases

List imported codebases 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)
bank_id
required
string (Bank Id)
name
required
string (Name)
source_type
required
string (Source Type)
object (CodebaseSourceConfigResponse)

Normalized source configuration for a codebase.

Current Snapshot Id (string) or Current Snapshot Id (null) (Current Snapshot Id)
Approved Snapshot Id (string) or Approved Snapshot Id (null) (Approved Snapshot Id)
Source Ref (string) or Source Ref (null) (Source Ref)
Source Commit Sha (string) or Source Commit Sha (null) (Source Commit Sha)
Snapshot Status (string) or Snapshot Status (null) (Snapshot Status)
Approved Source Ref (string) or Approved Source Ref (null) (Approved Source Ref)
Approved Source Commit Sha (string) or Approved Source Commit Sha (null) (Approved Source Commit Sha)
Approved Snapshot Status (string) or Approved Snapshot Status (null) (Approved Snapshot Status)
Approval Status (string) or Approval Status (null) (Approval Status)
Memory Status (string) or Memory Status (null) (Memory Status)
object (CodebaseSnapshotStatsResponse)

Snapshot-level deterministic indexing stats.

object (CodebaseReviewCountsResponse)

Counts of routed review items in the current snapshot.

cluster_count
integer (Cluster Count)
Default: 0
related_chunk_count
integer (Related Chunk Count)
Default: 0
parse_coverage
number (Parse Coverage)
Default: 0
Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)
Snapshot Created At (string) or Snapshot Created At (null) (Snapshot Created At)
Snapshot Updated At (string) or Snapshot Updated At (null) (Snapshot Updated At)
Approved Snapshot Updated At (string) or Approved Snapshot Updated At (null) (Approved Snapshot Updated At)

Response samples

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

Get codebase

Get codebase metadata plus current snapshot summary.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase 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_type
required
string (Source Type)
object (CodebaseSourceConfigResponse)

Normalized source configuration for a codebase.

Current Snapshot Id (string) or Current Snapshot Id (null) (Current Snapshot Id)
Approved Snapshot Id (string) or Approved Snapshot Id (null) (Approved Snapshot Id)
Source Ref (string) or Source Ref (null) (Source Ref)
Source Commit Sha (string) or Source Commit Sha (null) (Source Commit Sha)
Snapshot Status (string) or Snapshot Status (null) (Snapshot Status)
Approved Source Ref (string) or Approved Source Ref (null) (Approved Source Ref)
Approved Source Commit Sha (string) or Approved Source Commit Sha (null) (Approved Source Commit Sha)
Approved Snapshot Status (string) or Approved Snapshot Status (null) (Approved Snapshot Status)
Approval Status (string) or Approval Status (null) (Approval Status)
Memory Status (string) or Memory Status (null) (Memory Status)
object (CodebaseSnapshotStatsResponse)

Snapshot-level deterministic indexing stats.

object (CodebaseReviewCountsResponse)

Counts of routed review items in the current snapshot.

cluster_count
integer (Cluster Count)
Default: 0
related_chunk_count
integer (Related Chunk Count)
Default: 0
parse_coverage
number (Parse Coverage)
Default: 0
Created At (string) or Created At (null) (Created At)
Updated At (string) or Updated At (null) (Updated At)
Snapshot Created At (string) or Snapshot Created At (null) (Snapshot Created At)
Snapshot Updated At (string) or Snapshot Updated At (null) (Snapshot Updated At)
Approved Snapshot Updated At (string) or Approved Snapshot Updated At (null) (Approved Snapshot Updated At)

Response samples

Content type
application/json
{
  • "id": "string",
  • "bank_id": "string",
  • "name": "string",
  • "source_type": "string",
  • "source_config": {
    },
  • "current_snapshot_id": "string",
  • "approved_snapshot_id": "string",
  • "source_ref": "string",
  • "source_commit_sha": "string",
  • "snapshot_status": "string",
  • "approved_source_ref": "string",
  • "approved_source_commit_sha": "string",
  • "approved_snapshot_status": "string",
  • "approval_status": "string",
  • "memory_status": "string",
  • "stats": {
    },
  • "review_counts": {
    },
  • "cluster_count": 0,
  • "related_chunk_count": 0,
  • "parse_coverage": 0,
  • "created_at": "string",
  • "updated_at": "string",
  • "snapshot_created_at": "string",
  • "snapshot_updated_at": "string",
  • "approved_snapshot_updated_at": "string"
}

Get codebase review summary

Return review queue counts, parse coverage, related chunk counts, and deterministic diagnostics for the current snapshot.

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

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
Snapshot Status (string) or Snapshot Status (null) (Snapshot Status)
Approval Status (string) or Approval Status (null) (Approval Status)
Memory Status (string) or Memory Status (null) (Memory Status)
object (CodebaseReviewCountsResponse)

Counts of routed review items in the current snapshot.

cluster_count
integer (Cluster Count)
Default: 0
related_chunk_count
integer (Related Chunk Count)
Default: 0
parse_coverage
number (Parse Coverage)
Default: 0
object (CodebaseReviewChangedSummaryResponse)

Changed-file summary for the current review snapshot.

Array of objects (Diagnostics)
Default: []

Response samples

Content type
application/json
{
  • "codebase_id": "string",
  • "snapshot_id": "string",
  • "snapshot_status": "string",
  • "approval_status": "string",
  • "memory_status": "string",
  • "review_counts": {
    },
  • "cluster_count": 0,
  • "related_chunk_count": 0,
  • "parse_coverage": 0,
  • "changed_summary": {
    },
  • "diagnostics": [ ]
}

List codebase review chunks

Return cursor-paginated semantic chunks for the current codebase snapshot.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
query Parameters
Path Prefix (string) or Path Prefix (null) (Path Prefix)
Language (string) or Language (null) (Language)
Cluster Id (string) or Cluster Id (null) (Cluster Id)
Route Target (string) or Route Target (null) (Route Target)
changed_only
boolean (Changed Only)
Default: false
Kind (string) or Kind (null) (Kind)
Q (string) or Q (null) (Q)
limit
integer (Limit) [ 1 .. 100 ]
Default: 25
Cursor (string) or Cursor (null) (Cursor)
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
Min Significance (number) or Min Significance (null) (Min Significance)
Max Significance (number) or Max Significance (null) (Max Significance)
File Role (string) or File Role (null) (File Role)
Auto Route Reason (string) or Auto Route Reason (null) (Auto Route Reason)
Has Safety Tag (boolean) or Has Safety Tag (null) (Has Safety Tag)
Route Source (string) or Route Source (null) (Route Source)
Order By (string) or Order By (null) (Order By)

One of significance | review | path | complexity | pagerank

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

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
required
Array of objects (Items)
Next Cursor (string) or Next Cursor (null) (Next Cursor)
has_more
boolean (Has More)
Default: false

Response samples

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

Get codebase chunk detail

Return detailed code preview, related chunks, symbols, and impact edges for one chunk.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
chunk_id
required
string (Chunk Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
id
required
string (Id)
chunk_key
required
string (Chunk Key)
path
required
string (Path)
Language (string) or Language (null) (Language)
kind
required
string (Kind)
label
required
string (Label)
preview_text
required
string (Preview Text)
start_line
required
integer (Start Line)
end_line
required
integer (End Line)
Container (string) or Container (null) (Container)
Parent Symbol (string) or Parent Symbol (null) (Parent Symbol)
Parent Fq Name (string) or Parent Fq Name (null) (Parent Fq Name)
parse_confidence
number (Parse Confidence)
Default: 0
Cluster Id (string) or Cluster Id (null) (Cluster Id)
Cluster Label (string) or Cluster Label (null) (Cluster Label)
route_target
required
string (Route Target)
Route Source (string) or Route Source (null) (Route Source)
change_kind
required
string (Change Kind)
related_count
integer (Related Count)
Default: 0
Document Id (string) or Document Id (null) (Document Id)
significance_score
number (Significance Score)
Default: 0
Significance Components (object) or Significance Components (null) (Significance Components)
File Role (string) or File Role (null) (File Role)
Auto Route Reason (string) or Auto Route Reason (null) (Auto Route Reason)
Complexity Score (number) or Complexity Score (null) (Complexity Score)
safety_tags
Array of strings (Safety Tags)
Default: []
Pagerank Centrality (number) or Pagerank Centrality (null) (Pagerank Centrality)
fanin_count
integer (Fanin Count)
Default: 0
snapshot_id
required
string (Snapshot Id)
content_text
required
string (Content Text)
Array of objects (Related Chunks)
Default: []
Array of objects (Symbols)
Default: []
Array of objects (Impact Edges)
Default: []
Array of objects (Cluster Members)
Default: []

Response samples

Content type
application/json
{
  • "id": "string",
  • "chunk_key": "string",
  • "path": "string",
  • "language": "string",
  • "kind": "string",
  • "label": "string",
  • "preview_text": "string",
  • "start_line": 0,
  • "end_line": 0,
  • "container": "string",
  • "parent_symbol": "string",
  • "parent_fq_name": "string",
  • "parse_confidence": 0,
  • "cluster_id": "string",
  • "cluster_label": "string",
  • "route_target": "string",
  • "route_source": "string",
  • "change_kind": "string",
  • "related_count": 0,
  • "document_id": "string",
  • "significance_score": 0,
  • "significance_components": { },
  • "file_role": "string",
  • "auto_route_reason": "string",
  • "complexity_score": 0,
  • "safety_tags": [ ],
  • "pagerank_centrality": 0,
  • "fanin_count": 0,
  • "snapshot_id": "string",
  • "content_text": "string",
  • "related_chunks": [ ],
  • "symbols": [ ],
  • "impact_edges": [ ],
  • "cluster_members": [ ]
}

Route review items

Bulk-route chunk review items to memory, research, dismissed, or back to unrouted.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
item_ids
required
Array of strings (Item Ids)
target
required
string (Target)
Enum: "memory" "research" "dismissed" "unrouted"
queue_memory_import
boolean (Queue Memory Import)
Default: false
memory_ingest_mode
string (Memory Ingest Mode)
Default: "direct"
Enum: "direct" "retain"

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
snapshot_id
required
string (Snapshot Id)
updated_count
required
integer (Updated Count)
target
required
string (Target)
Operation Id (string) or Operation Id (null) (Operation Id)
queued_for_memory
boolean (Queued For Memory)
Default: false
memory_ingest_mode
string (Memory Ingest Mode)
Default: "direct"
Enum: "direct" "retain"
object (CodebaseReviewCountsResponse)

Counts of routed review items in the current snapshot.

Request samples

Content type
application/json
{
  • "item_ids": [
    ],
  • "target": "memory",
  • "queue_memory_import": false,
  • "memory_ingest_mode": "direct"
}

Response samples

Content type
application/json
{
  • "codebase_id": "string",
  • "snapshot_id": "string",
  • "updated_count": 0,
  • "target": "string",
  • "operation_id": "string",
  • "queued_for_memory": false,
  • "memory_ingest_mode": "direct",
  • "review_counts": {
    }
}

List research queue items

Return chunks currently routed to the codebase research queue.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
query Parameters
Cursor (string) or Cursor (null) (Cursor)
limit
integer (Limit) [ 1 .. 100 ]
Default: 25
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
required
Array of objects (Items)
Next Cursor (string) or Next Cursor (null) (Next Cursor)
has_more
boolean (Has More)
Default: false

Response samples

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

Get codebase Repo Map

Return the snapshot Repo Map artifact (top-K ranked tags + module dependency edges).

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
query Parameters
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
Generated At (string) or Generated At (null) (Generated At)
Repo Map (object) or Repo Map (null) (Repo Map)

Response samples

Content type
application/json
{
  • "codebase_id": "string",
  • "snapshot_id": "string",
  • "generated_at": "string",
  • "repo_map": { }
}

List Module Briefs

Return Module Brief artifacts for a snapshot.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
query Parameters
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
limit
integer (Limit) [ 1 .. 500 ]
Default: 100
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
Array of objects (Items)
Default: []

Response samples

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

List Symbol Cards

Return paginated Symbol Card artifacts ordered by significance.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
query Parameters
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
limit
integer (Limit) [ 1 .. 500 ]
Default: 100
Cursor (string) or Cursor (null) (Cursor)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
Array of objects (Items)
Default: []
Next Cursor (string) or Next Cursor (null) (Next Cursor)
has_more
boolean (Has More)
Default: false

Response samples

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

Get a Symbol Card

Return one Symbol Card artifact by fully-qualified symbol id.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
symbol_id
required
string (Symbol Id)
query Parameters
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
snapshot_id
required
string (Snapshot Id)
required
object (Symbol Card)

Response samples

Content type
application/json
{
  • "codebase_id": "string",
  • "snapshot_id": "string",
  • "symbol_card": { }
}

Curate codebase by intent

Rank Symbol Cards + chunks against a free-text intent. Returns top clusters and symbol cards.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
intent
required
string (Intent)
Scope Hint (string) or Scope Hint (null) (Scope Hint)
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
top_k_clusters
integer (Top K Clusters) [ 1 .. 50 ]
Default: 10
top_k_symbols
integer (Top K Symbols) [ 1 .. 100 ]
Default: 20
include_dismissed
boolean (Include Dismissed)
Default: false

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
intent
required
string (Intent)
Scope Hint (string) or Scope Hint (null) (Scope Hint)
Array of objects (Clusters)
Default: []
Array of objects (Symbol Cards)
Default: []
Array of objects (Unclustered)
Default: []
total_candidates
integer (Total Candidates)
Default: 0

Request samples

Content type
application/json
{
  • "intent": "string",
  • "scope_hint": "string",
  • "snapshot_id": "string",
  • "top_k_clusters": 10,
  • "top_k_symbols": 20,
  • "include_dismissed": false
}

Response samples

Content type
application/json
{
  • "codebase_id": "string",
  • "snapshot_id": "string",
  • "intent": "string",
  • "scope_hint": "string",
  • "clusters": [ ],
  • "symbol_cards": [ ],
  • "unclustered": [ ],
  • "total_candidates": 0
}

Get triage settings

Return per-codebase auto-triage settings.

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

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
required
object (CodebaseTriageSettings)

Per-codebase triage thresholds and provider toggles.

Response samples

Content type
application/json
{
  • "codebase_id": "string",
  • "settings": {
    }
}

Update triage settings

Replace per-codebase auto-triage settings.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
score_threshold_high
number (Score Threshold High) [ 0 .. 1 ]
Default: 0.62
centrality_threshold
number (Centrality Threshold) [ 0 .. 1 ]
Default: 0.35
safety_threshold
number (Safety Threshold) [ 0 .. 1 ]
Default: 0.25
embedding_provider
string (Embedding Provider)
Default: "jina_local"
enable_safety_scan
boolean (Enable Safety Scan)
Default: true
enable_semgrep
boolean (Enable Semgrep)
Default: false
Semgrep Rulepack (string) or Semgrep Rulepack (null) (Semgrep Rulepack)
Scip Index Path (string) or Scip Index Path (null) (Scip Index Path)

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
required
object (CodebaseTriageSettings)

Per-codebase triage thresholds and provider toggles.

Request samples

Content type
application/json
{
  • "score_threshold_high": 0.62,
  • "centrality_threshold": 0.35,
  • "safety_threshold": 0.25,
  • "embedding_provider": "jina_local",
  • "enable_safety_scan": true,
  • "enable_semgrep": false,
  • "semgrep_rulepack": "string",
  • "scip_index_path": "string"
}

Response samples

Content type
application/json
{
  • "codebase_id": "string",
  • "settings": {
    }
}

List codebase files

Return the repo map and filtered file listing for a codebase snapshot.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
query Parameters
Path Prefix (string) or Path Prefix (null) (Path Prefix)

Only include files under this path prefix

Language (string) or Language (null) (Language)

Filter by detected language

changed_only
boolean (Changed Only)
Default: false

Only include changed or added files

Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)

Optional snapshot override

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

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
Source Ref (string) or Source Ref (null) (Source Ref)
Source Commit Sha (string) or Source Commit Sha (null) (Source Commit Sha)
Snapshot Status (string) or Snapshot Status (null) (Snapshot Status)
required
Array of objects (Items)

Response samples

Content type
application/json
{
  • "codebase_id": "string",
  • "snapshot_id": "string",
  • "source_ref": "string",
  • "source_commit_sha": "string",
  • "snapshot_status": "string",
  • "items": [
    ]
}

Search codebase symbols

Search deterministic symbols by exact, prefix, or fuzzy match.

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

Symbol query

Kind (string) or Kind (null) (Kind)

Optional symbol kind filter

Path Prefix (string) or Path Prefix (null) (Path Prefix)

Only search under this path prefix

Language (string) or Language (null) (Language)

Filter by detected language

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

Maximum number of symbol matches

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

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
required
Array of objects (Items)

Response samples

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

Analyze codebase impact

Run deterministic impact analysis from a path, symbol, or query over the codebase graph.

path Parameters
bank_id
required
string (Bank Id)
codebase_id
required
string (Codebase Id)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Request Body schema: application/json
required
Path (string) or Path (null) (Path)
Symbol (string) or Symbol (null) (Symbol)
Query (string) or Query (null) (Query)
max_depth
integer (Max Depth) [ 1 .. 8 ]
Default: 2
limit
integer (Limit) [ 1 .. 200 ]
Default: 50

Responses

Response Schema: application/json
codebase_id
required
string (Codebase Id)
Snapshot Id (string) or Snapshot Id (null) (Snapshot Id)
CodebaseImpactSeedResponse (object) or null
required
Array of objects (Impacted Files)
required
Array of objects (Matched Symbols)
required
Array of objects (Edges)
explanation
required
string (Explanation)

Request samples

Content type
application/json
{
  • "path": "string",
  • "symbol": "string",
  • "query": "string",
  • "max_depth": 2,
  • "limit": 50
}

Response samples

Content type
application/json
{
  • "codebase_id": "string",
  • "snapshot_id": "string",
  • "seed": {
    },
  • "impacted_files": [
    ],
  • "matched_symbols": [
    ],
  • "edges": [
    ],
  • "explanation": "string"
}

Admin

Admin system health

Returns DB pool stats, migration version, and active worker count.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
status
required
string (Status)
api_version
required
string (Api Version)
db_pool_min
required
integer (Db Pool Min)
db_pool_max
required
integer (Db Pool Max)
db_pool_size
required
integer (Db Pool Size)
db_pool_free
required
integer (Db Pool Free)
required
Migration Version (string) or Migration Version (null) (Migration Version)
worker_count
required
integer (Worker Count)
admin_schema
required
string (Admin Schema)

Response samples

Content type
application/json
{
  • "status": "string",
  • "api_version": "string",
  • "db_pool_min": 0,
  • "db_pool_max": 0,
  • "db_pool_size": 0,
  • "db_pool_free": 0,
  • "migration_version": "string",
  • "worker_count": 0,
  • "admin_schema": "string"
}

Admin system health

Returns DB pool stats, migration version, and active worker count.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
status
required
string (Status)
api_version
required
string (Api Version)
db_pool_min
required
integer (Db Pool Min)
db_pool_max
required
integer (Db Pool Max)
db_pool_size
required
integer (Db Pool Size)
db_pool_free
required
integer (Db Pool Free)
required
Migration Version (string) or Migration Version (null) (Migration Version)
worker_count
required
integer (Worker Count)
admin_schema
required
string (Admin Schema)

Response samples

Content type
application/json
{
  • "status": "string",
  • "api_version": "string",
  • "db_pool_min": 0,
  • "db_pool_max": 0,
  • "db_pool_size": 0,
  • "db_pool_free": 0,
  • "migration_version": "string",
  • "worker_count": 0,
  • "admin_schema": "string"
}

List all tenants

Returns all tenants known to the tenant extension with bank counts.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
Array
schema_name
required
string (Schema Name)
bank_count
required
integer (Bank Count)

Response samples

Content type
application/json
[
  • {
    }
]

List all tenants

Returns all tenants known to the tenant extension with bank counts.

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
Array
schema_name
required
string (Schema Name)
bank_count
required
integer (Bank Count)

Response samples

Content type
application/json
[
  • {
    }
]

List banks in a tenant schema

Returns all bank IDs and names within the specified tenant schema.

path Parameters
schema
required
string (Schema)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
Array
property name*
additional property
any

Response samples

Content type
application/json
[
  • { }
]

List banks in a tenant schema

Returns all bank IDs and names within the specified tenant schema.

path Parameters
schema
required
string (Schema)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
Array
property name*
additional property
any

Response samples

Content type
application/json
[
  • { }
]

List active workers

Lists workers with pending/stuck operation counts from async_operations.

query Parameters
schema
string (Schema)
Default: "public"

Schema to inspect

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
Array
worker_id
required
string (Worker Id)
schema_name
required
string (Schema Name)
pending_count
required
integer (Pending Count)
stuck_count
required
integer (Stuck Count)
required
Last Seen At (string) or Last Seen At (null) (Last Seen At)

Response samples

Content type
application/json
[
  • {
    }
]

List active workers

Lists workers with pending/stuck operation counts from async_operations.

query Parameters
schema
string (Schema)
Default: "public"

Schema to inspect

header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
Array
worker_id
required
string (Worker Id)
schema_name
required
string (Schema Name)
pending_count
required
integer (Pending Count)
stuck_count
required
integer (Stuck Count)
required
Last Seen At (string) or Last Seen At (null) (Last Seen At)

Response samples

Content type
application/json
[
  • {
    }
]

Decommission a worker

Release all tasks claimed by the specified worker so another worker can pick them up. Use worker_id='all_stuck' to release all tasks with no active worker.

path Parameters
worker_id
required
string (Worker Id)
query Parameters
schema
string (Schema)
Default: "public"
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)
Request Body schema: application/json
required
release_stuck
boolean (Release Stuck)
Default: true

Re-queue stuck tasks so another worker can pick them up (default: true).

Responses

Response Schema: application/json
worker_id
required
string (Worker Id)
released_count
required
integer (Released Count)

Request samples

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

Response samples

Content type
application/json
{
  • "worker_id": "string",
  • "released_count": 0
}

Decommission a worker

Release all tasks claimed by the specified worker so another worker can pick them up. Use worker_id='all_stuck' to release all tasks with no active worker.

path Parameters
worker_id
required
string (Worker Id)
query Parameters
schema
string (Schema)
Default: "public"
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)
Request Body schema: application/json
required
release_stuck
boolean (Release Stuck)
Default: true

Re-queue stuck tasks so another worker can pick them up (default: true).

Responses

Response Schema: application/json
worker_id
required
string (Worker Id)
released_count
required
integer (Released Count)

Request samples

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

Response samples

Content type
application/json
{
  • "worker_id": "string",
  • "released_count": 0
}

List operations across all tenants

Returns recent async operations across all tenant schemas visible to the superuser.

query Parameters
schema
string (Schema)
Default: "public"
Status (string) or Status (null) (Status)
limit
integer (Limit) [ 1 .. 200 ]
Default: 50
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
Array
operation_id
required
string (Operation Id)
bank_id
required
string (Bank Id)
schema_name
required
string (Schema Name)
operation_type
required
string (Operation Type)
status
required
string (Status)
required
Worker Id (string) or Worker Id (null) (Worker Id)
created_at
required
string (Created At)
required
Updated At (string) or Updated At (null) (Updated At)
required
Error Message (string) or Error Message (null) (Error Message)

Response samples

Content type
application/json
[
  • {
    }
]

List operations across all tenants

Returns recent async operations across all tenant schemas visible to the superuser.

query Parameters
schema
string (Schema)
Default: "public"
Status (string) or Status (null) (Status)
limit
integer (Limit) [ 1 .. 200 ]
Default: 50
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
Array
operation_id
required
string (Operation Id)
bank_id
required
string (Bank Id)
schema_name
required
string (Schema Name)
operation_type
required
string (Operation Type)
status
required
string (Status)
required
Worker Id (string) or Worker Id (null) (Worker Id)
created_at
required
string (Created At)
required
Updated At (string) or Updated At (null) (Updated At)
required
Error Message (string) or Error Message (null) (Error Message)

Response samples

Content type
application/json
[
  • {
    }
]

Trigger consolidation for all banks in a schema

Enqueues a consolidation task for every bank in the given schema.

path Parameters
schema
required
string (Schema)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
property name*
additional property
any

Response samples

Content type
application/json
{ }

Trigger consolidation for all banks in a schema

Enqueues a consolidation task for every bank in the given schema.

path Parameters
schema
required
string (Schema)
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
property name*
additional property
any

Response samples

Content type
application/json
{ }

List API keys

Returns all API keys (redacted — raw key is never returned after creation).

query Parameters
schema
string (Schema)
Default: "public"
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
Array
id
required
string (Id)
name
required
string (Name)
role
required
string (Role)
schema_name
required
string (Schema Name)
required
Array of Allowed Bank Ids (strings) or Allowed Bank Ids (null) (Allowed Bank Ids)
created_at
required
string (Created At)
required
Expires At (string) or Expires At (null) (Expires At)
required
Revoked At (string) or Revoked At (null) (Revoked At)
Raw Key (string) or Raw Key (null) (Raw Key)

Response samples

Content type
application/json
[
  • {
    }
]

List API keys

Returns all API keys (redacted — raw key is never returned after creation).

query Parameters
schema
string (Schema)
Default: "public"
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
Array
id
required
string (Id)
name
required
string (Name)
role
required
string (Role)
schema_name
required
string (Schema Name)
required
Array of Allowed Bank Ids (strings) or Allowed Bank Ids (null) (Allowed Bank Ids)
created_at
required
string (Created At)
required
Expires At (string) or Expires At (null) (Expires At)
required
Revoked At (string) or Revoked At (null) (Revoked At)
Raw Key (string) or Raw Key (null) (Raw Key)

Response samples

Content type
application/json
[
  • {
    }
]

Create API key

Creates a new API key and returns the raw key once. Store it securely — it cannot be retrieved again.

query Parameters
schema
string (Schema)
Default: "public"
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)
Request Body schema: application/json
required
name
required
string (Name)

Human-readable label for this key

role
string (Role)
Default: "user"

Role: superuser | admin | user

schema_name
string (Schema Name)
Default: "public"

PostgreSQL schema this key operates in

Array of Allowed Bank Ids (strings) or Allowed Bank Ids (null) (Allowed Bank Ids)

Restrict access to specific banks. None = unrestricted.

Expires Days (integer) or Expires Days (null) (Expires Days)

Days until key expires. None = never expires.

Responses

Response Schema: application/json
id
required
string (Id)
name
required
string (Name)
role
required
string (Role)
schema_name
required
string (Schema Name)
required
Array of Allowed Bank Ids (strings) or Allowed Bank Ids (null) (Allowed Bank Ids)
created_at
required
string (Created At)
required
Expires At (string) or Expires At (null) (Expires At)
required
Revoked At (string) or Revoked At (null) (Revoked At)
Raw Key (string) or Raw Key (null) (Raw Key)

Request samples

Content type
application/json
{
  • "name": "string",
  • "role": "user",
  • "schema_name": "public",
  • "allowed_bank_ids": [
    ],
  • "expires_days": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "role": "string",
  • "schema_name": "string",
  • "allowed_bank_ids": [
    ],
  • "created_at": "string",
  • "expires_at": "string",
  • "revoked_at": "string",
  • "raw_key": "string"
}

Create API key

Creates a new API key and returns the raw key once. Store it securely — it cannot be retrieved again.

query Parameters
schema
string (Schema)
Default: "public"
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)
Request Body schema: application/json
required
name
required
string (Name)

Human-readable label for this key

role
string (Role)
Default: "user"

Role: superuser | admin | user

schema_name
string (Schema Name)
Default: "public"

PostgreSQL schema this key operates in

Array of Allowed Bank Ids (strings) or Allowed Bank Ids (null) (Allowed Bank Ids)

Restrict access to specific banks. None = unrestricted.

Expires Days (integer) or Expires Days (null) (Expires Days)

Days until key expires. None = never expires.

Responses

Response Schema: application/json
id
required
string (Id)
name
required
string (Name)
role
required
string (Role)
schema_name
required
string (Schema Name)
required
Array of Allowed Bank Ids (strings) or Allowed Bank Ids (null) (Allowed Bank Ids)
created_at
required
string (Created At)
required
Expires At (string) or Expires At (null) (Expires At)
required
Revoked At (string) or Revoked At (null) (Revoked At)
Raw Key (string) or Raw Key (null) (Raw Key)

Request samples

Content type
application/json
{
  • "name": "string",
  • "role": "user",
  • "schema_name": "public",
  • "allowed_bank_ids": [
    ],
  • "expires_days": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "role": "string",
  • "schema_name": "string",
  • "allowed_bank_ids": [
    ],
  • "created_at": "string",
  • "expires_at": "string",
  • "revoked_at": "string",
  • "raw_key": "string"
}

Update API key

Update name, role, or allowed_bank_ids for an existing key.

path Parameters
key_id
required
string (Key Id)
query Parameters
schema
string (Schema)
Default: "public"
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Role (string) or Role (null) (Role)
Array of Allowed Bank Ids (strings) or Allowed Bank Ids (null) (Allowed Bank Ids)

Responses

Response Schema: application/json
id
required
string (Id)
name
required
string (Name)
role
required
string (Role)
schema_name
required
string (Schema Name)
required
Array of Allowed Bank Ids (strings) or Allowed Bank Ids (null) (Allowed Bank Ids)
created_at
required
string (Created At)
required
Expires At (string) or Expires At (null) (Expires At)
required
Revoked At (string) or Revoked At (null) (Revoked At)
Raw Key (string) or Raw Key (null) (Raw Key)

Request samples

Content type
application/json
{
  • "name": "string",
  • "role": "string",
  • "allowed_bank_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "role": "string",
  • "schema_name": "string",
  • "allowed_bank_ids": [
    ],
  • "created_at": "string",
  • "expires_at": "string",
  • "revoked_at": "string",
  • "raw_key": "string"
}

Update API key

Update name, role, or allowed_bank_ids for an existing key.

path Parameters
key_id
required
string (Key Id)
query Parameters
schema
string (Schema)
Default: "public"
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)
Request Body schema: application/json
required
Name (string) or Name (null) (Name)
Role (string) or Role (null) (Role)
Array of Allowed Bank Ids (strings) or Allowed Bank Ids (null) (Allowed Bank Ids)

Responses

Response Schema: application/json
id
required
string (Id)
name
required
string (Name)
role
required
string (Role)
schema_name
required
string (Schema Name)
required
Array of Allowed Bank Ids (strings) or Allowed Bank Ids (null) (Allowed Bank Ids)
created_at
required
string (Created At)
required
Expires At (string) or Expires At (null) (Expires At)
required
Revoked At (string) or Revoked At (null) (Revoked At)
Raw Key (string) or Raw Key (null) (Raw Key)

Request samples

Content type
application/json
{
  • "name": "string",
  • "role": "string",
  • "allowed_bank_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "role": "string",
  • "schema_name": "string",
  • "allowed_bank_ids": [
    ],
  • "created_at": "string",
  • "expires_at": "string",
  • "revoked_at": "string",
  • "raw_key": "string"
}

Revoke API key

Soft-deletes an API key by setting revoked_at. The key is immediately inactive.

path Parameters
key_id
required
string (Key Id)
query Parameters
schema
string (Schema)
Default: "public"
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
property name*
additional property
string

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Revoke API key

Soft-deletes an API key by setting revoked_at. The key is immediately inactive.

path Parameters
key_id
required
string (Key Id)
query Parameters
schema
string (Schema)
Default: "public"
header Parameters
Authorization (string) or Authorization (null) (Authorization)
X-Api-Key (string) or X-Api-Key (null) (X-Api-Key)

Responses

Response Schema: application/json
property name*
additional property
string

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}