AI operations. Substrio docs

`ai`

`ai.ask`

Ask a question against a knowledge collection.

Route: ANY ask
Auth: App key or user session; your security rules apply none
CLI: substrio op ai.ask

Parameters

Name	In	Type	Required	Description
`collection`	body	`string`	Yes
`question`	body	`string`	Yes

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URLask" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`ai.ask.route`

Ask a question against a knowledge collection over HTTP.

Route: POST /v1/{collection}/_ask
Auth: App key or user session; your security rules apply none
MCP tool: substrio_ask
CLI: substrio op ai.ask.route

Parameters

Name	In	Type	Required	Description
`collection`	path	`string`	Yes	The collection's name, as `collection.list` names it.
`question`	body	`string`	Yes
`search_k`	body	`integer`	No
`expand_before`	body	`integer`	No
`expand_after`	body	`integer`	No

Response

Field	Type	Present
`context`	`array of object`	Always
`citations`	`array of integer`	Always
`source_documents`	`array of integer`	When set
`search_hits`	`integer`	Always
`chunks_used`	`integer`	Always
`collection`	`string`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/$COLLECTION/_ask" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"question"}'

Read the agent requests of the app's audit trail (action agent.request in audit.list), newest first: each has its actor, the operation it called and its outcome. Options: since (Unix seconds; the last hour when neither since nor context_id is given), limit (default 50), context_id (an agent session id) and tool_name (needs since or context_id).

Route: GET /v1/_ai/audit
Auth: App key tenant
MCP tool: substrio_ai_audit
CLI: substrio op ai.audit

Parameters

Name	In	Type	Required	Description
`limit`	query	`integer (0 or more)`	No	the most items to return.
`since`	query	`integer (0 or more)`	No	only entries at or after this Unix time, in seconds.
`context_id`	query	`string`	No	only audit entries of this agent context.
`tool_name`	query	`string`	No	only audit entries of this tool.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_ai/audit" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`ai.cross_search`

Search multiple vector fields in one collection.

Route: POST /v1/{collection}/_cross_search
Auth: App key or user session; your security rules apply none
CLI: substrio op ai.cross_search

Parameters

Name	In	Type	Required	Description
`collection`	path	`string`	Yes	The collection's name, as `collection.list` names it.
`query`	body	`string`	Yes
`fields`	body	`array of string`	No
`k`	body	`integer`	No	Minimum 1. Default `10`.
`limit`	body	`integer`	No	Minimum 1. Default `10`.

Response

Field	Type	Present
`data`	`array of object`	Always
`count`	`integer`	Always
`fields_searched`	`array of string`	Always
`fields_skipped`	`array of string`	When set

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/$COLLECTION/_cross_search" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"query"}'

`ai.expand`

Expand context around a chunk.

Route: ANY expand
Auth: App key or user session; your security rules apply none
CLI: substrio op ai.expand

Parameters

Name	In	Type	Required	Description
`collection`	body	`string`	Yes
`chunk_id`	body	`string`	Yes

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URLexpand" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`ai.expand.route`

Expand one knowledge chunk of a collection with its surrounding chunks; see the schema.

Route: POST /v1/{collection}/_expand
Auth: App key or user session; your security rules apply none
MCP tool: substrio_expand
CLI: substrio op ai.expand.route

Parameters

Name	In	Type	Required	Description
`collection`	path	`string`	Yes	The collection's name, as `collection.list` names it.
`_id`	body	`string or integer`	Yes
`before`	body	`integer`	No
`after`	body	`integer`	No

Response

Field	Type	Present
`chunks`	`array of object`	Always
`_parent_id`	`integer`	Always
`_chunk_total`	`integer`	Always
`expandable_before`	`integer`	Always
`expandable_after`	`integer`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/$COLLECTION/_expand" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"_id":"_id"}'

`ai.feedback`

Record search relevance feedback.

Route: ANY feedback
Auth: App key or user session; your security rules apply none
CLI: substrio op ai.feedback

Parameters

Name	In	Type	Required
`collection`	body	`string`	Yes
`query_hash`	body	`string`	Yes
`document_id`	body	`string`	Yes
`signal`	body	`string`	Yes

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URLfeedback" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`ai.feedback.analytics`

Read aggregated search feedback.

Route: GET /v1/{collection}/_feedback/analytics
Auth: App key or user session; your security rules apply none
CLI: substrio op ai.feedback.analytics

Parameters

Name	In	Type	Required	Description
`collection`	path	`string`	Yes	The collection's name, as `collection.list` names it.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/$COLLECTION/_feedback/analytics" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`ai.feedback.list`

List recent search feedback.

Route: GET /v1/{collection}/_feedback
Auth: App key or user session; your security rules apply none
CLI: substrio op ai.feedback.list

Parameters

Name	In	Type	Required	Description
`collection`	path	`string`	Yes	The collection's name, as `collection.list` names it.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/$COLLECTION/_feedback" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`ai.feedback.write`

Record search relevance feedback over HTTP.

Route: POST /v1/{collection}/_feedback
Auth: App key or user session; your security rules apply none
MCP tool: substrio_feedback
CLI: substrio op ai.feedback.write

Parameters

Name	In	Type	Required	Description
`collection`	path	`string`	Yes	The collection's name, as `collection.list` names it.
`query`	body	`string`	Yes
`doc_id`	body	`string or integer`	Yes
`signal`	body	`"click" \| "star" \| "irrelevant"`	Yes
`user_id`	body	`string`	No

Response

Field	Type	Present
`recorded`	`any`	Always
`query_hash`	`string`	Always
`aggregate_score`	`number`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/$COLLECTION/_feedback" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"query","doc_id":"doc_id","signal":"click"}'

`ai.models`

List the distinct provider and model pairs the app's collections' RAG configurations use.

Route: GET /v1/_models
Auth: App key tenant
MCP tool: substrio_ai_models
CLI: substrio op ai.models

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_models" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`ai.search`

Search a knowledge collection.

Route: ANY search
Auth: App key or user session; your security rules apply none
CLI: substrio op ai.search

Parameters

Name	In	Type	Required	Description
`collection`	body	`string`	Yes
`query`	body	`string`	Yes

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URLsearch" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`ai.tool.invoke`

Invoke a discovered administrative tool by operation ID.

Route: POST /v1/_tools/invoke
Auth: App key tenant
MCP tool: substrio_tool_invoke
CLI: substrio op ai.tool.invoke

Parameters

Name	In	Type	Required	Description
`operation_id`	body	`integer`	Yes	Minimum 1.
`method`	body	`string`	No
`captures`	body	`array of string`	No
`payload`	body	`any`	No

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_tools/invoke" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation_id":1}'

`ai.tools`

Describe administration tools available to the caller.

Route: GET /v1/_tools
Auth: App key tenant
CLI: substrio op ai.tools

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_tools" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`mcp`

`mcp.rpc`

Serve the tenant's tools to AI agents over MCP (JSON-RPC, Streamable HTTP).

Route: MCP and CLI only
Auth: App key or user session; your security rules apply none
CLI: substrio op mcp.rpc

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

substrio op mcp.rpc

`search`

`search.analytics`

Read search analytics for a collection.

Route: GET /v1/{collection}/_analytics/search
Auth: App key or user session; your security rules apply none
CLI: substrio op search.analytics

Parameters

Name	In	Type	Required	Description
`collection`	path	`string`	Yes	The collection's name, as `collection.list` names it.
`since`	query	`integer (0 or more)`	No	only entries at or after this Unix time, in seconds.
`top_n`	query	`integer (0 or more)`	No	how many top search terms to return.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/$COLLECTION/_analytics/search" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`thread`

`thread.ask`

Ask one question in an agent thread by id; see the schema.

Route: POST /v1/_threads/{id}/_ask
Auth: App key or user session; your security rules apply none
MCP tool: substrio_thread_ask
CLI: substrio op thread.ask

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The thread's id, as `thread.list` or `thread.create` returned it.
`question`	body	`string`	Yes
`search_k`	body	`integer`	No
`max_context_messages`	body	`integer`	No
`max_context_tokens`	body	`integer`	No

Response

Field	Type	Present
`context`	`array of object`	Always
`citations`	`array of integer`	Always
`conversation`	`array of object`	Always
`search_hits`	`integer`	Always
`rag_chunks`	`integer`	Always
`thread_id`	`string`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_threads/$ID/_ask" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"question"}'

`thread.create`

Create an agent thread, a conversation record; see the schema.

Route: POST /v1/_threads
Auth: App key or user session; your security rules apply none
MCP tool: substrio_thread_create
CLI: substrio op thread.create

Parameters

Name	In	Type	Required	Description
`title`	body	`string`	No
`max_messages`	body	`integer`	No
`max_context_tokens`	body	`integer`	No
`max_context_messages`	body	`integer`	No
`search_k`	body	`integer`	No
`expand_before`	body	`integer`	No
`expand_after`	body	`integer`	No
`system_prompt`	body	`string`	No
`model`	body	`string`	No
`auto_title`	body	`boolean`	No
`rag_collections`	body	`array of string`	No
`tool_preset`	body	`"read_only" \| "analyst" \| "curator" \| "operator"`	No
`tool_budget_max_calls`	body	`integer`	No
`tool_budget_max_writes`	body	`integer`	No
`write_collections`	body	`array of string`	No
`memory_collection`	body	`string`	No
`metadata`	body	`any`	No	Any value, stored as given.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_threads" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`thread.delete`

Delete one agent thread by its id (the route's {id}, as thread.list shows it).

Route: DELETE /v1/_threads/{id}
Auth: App key or user session; your security rules apply none
MCP tool: substrio_thread_delete
CLI: substrio op thread.delete

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The thread's id, as `thread.list` or `thread.create` returned it.

Response

Field	Type	Present	Description
`deleted`	`any`	Always
`id`	`string`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_threads/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`thread.get`

Read one agent thread by its id (the route's {id}, as thread.list shows it).

Route: GET /v1/_threads/{id}
Auth: App key or user session; your security rules apply none
MCP tool: substrio_thread_get
CLI: substrio op thread.get

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The thread's id, as `thread.list` or `thread.create` returned it.

Response

A JSON object.

Errors

THREAD_NOT_FOUND: call thread.list to find the right one.

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_threads/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`thread.list`

List the app's agent threads (conversation records); thread.get reads one by its id.

Route: GET /v1/_threads
Auth: App key or user session; your security rules apply none
MCP tool: substrio_thread_list
CLI: substrio op thread.list

Parameters

No parameters.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_threads" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`thread.message`

Append one message to an agent thread by id.

Route: POST /v1/_threads/{id}/messages
Auth: App key or user session; your security rules apply none
MCP tool: substrio_thread_message
CLI: substrio op thread.message

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The thread's id, as `thread.list` or `thread.create` returned it.
`role`	body	`"user" \| "assistant" \| "system" \| "tool" \| "summary"`	Yes
`content`	body	`string`	Yes
`metadata`	body	`any`	No	Any value, stored as given.

Response

Field	Type	Present
`id`	`string`	Always
`role`	`"user" \| "assistant" \| "system" \| "tool" \| "summary"`	Always
`created_at`	`integer`	Always
`token_count`	`integer`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_threads/$ID/messages" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"user","content":"content"}'

`thread.message.delete`

Delete one message of an agent thread: the route's thread {id} and {message_id}.

Route: DELETE /v1/_threads/{id}/messages/{message_id}
Auth: App key or user session; your security rules apply none
MCP tool: substrio_thread_message_delete
CLI: substrio op thread.message.delete

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The thread's id, as `thread.list` or `thread.create` returned it.
`message_id`	path	`string or integer`	Yes	The message's id, as `thread.messages.list` returned it.

Response

Field	Type	Present	Description
`deleted`	`any`	Always
`id`	`string`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X DELETE "$SUBSTRIO_URL/v1/_threads/$ID/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`thread.messages.list`

List the messages of one agent thread by id: options limit and order (asc or desc, default desc).

Route: GET /v1/_threads/{id}/messages
Auth: App key or user session; your security rules apply none
MCP tool: substrio_thread_messages_list
CLI: substrio op thread.messages.list

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The thread's id, as `thread.list` or `thread.create` returned it.
`limit`	query	`integer (0 or more)`	No	the most items to return.
`order`	query	`"asc" \| "desc"`	No	asc lists oldest first; desc (the default) newest first.

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl "$SUBSTRIO_URL/v1/_threads/$ID/messages" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`thread.prune`

Prune selected messages from an agent thread.

Route: POST /v1/_threads/{id}/_prune
Auth: App key or user session; your security rules apply none
MCP tool: substrio_thread_prune
CLI: substrio op thread.prune

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The thread's id, as `thread.list` or `thread.create` returned it.
`msg_ids`	body	`array of string`	No
`role`	body	`string`	No
`keep_last`	body	`integer`	No

Response

Field	Type	Present
`pruned`	`any`	Always
`deleted`	`integer`	Always
`remaining`	`integer`	Always

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_threads/$ID/_prune" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`thread.summarize`

Summarize one agent thread by its id (the route's {id}); see the schema for the options.

Route: POST /v1/_threads/{id}/_summarize
Auth: App key or user session; your security rules apply none
MCP tool: substrio_thread_summarize
CLI: substrio op thread.summarize

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The thread's id, as `thread.list` or `thread.create` returned it.
`keep_last`	body	`integer`	No

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X POST "$SUBSTRIO_URL/v1/_threads/$ID/_summarize" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"

`thread.update`

Change one agent thread by id; see the schema.

Route: PATCH /v1/_threads/{id}
Auth: App key or user session; your security rules apply none
MCP tool: substrio_thread_update
CLI: substrio op thread.update

Parameters

Name	In	Type	Required	Description
`id`	path	`string or integer`	Yes	The thread's id, as `thread.list` or `thread.create` returned it.
`title`	body	`string`	No
`status`	body	`"active" \| "archived"`	No
`max_messages`	body	`integer`	No
`max_context_tokens`	body	`integer`	No
`max_context_messages`	body	`integer`	No
`search_k`	body	`integer`	No
`expand_before`	body	`integer`	No
`expand_after`	body	`integer`	No
`system_prompt`	body	`string`	No
`model`	body	`string`	No

Response

A JSON object.

Errors

A failed call answers the error envelope with a typed code.

Example

curl -X PATCH "$SUBSTRIO_URL/v1/_threads/$ID" \
  -H "Authorization: Bearer $SUBSTRIO_KEY"