Extella API v0.7.0 — docs.extella.ai

Reference — v0.7.0

All 48 endpoints

v0.7.0 — 11 sections — 48 endpoints. Each card: verbatim description, exact request fields (* = required), per-endpoint response table, Python example.

⚡ General1 endpoint

GET/api/healthHealth Check

Description

Health Check. Retrieves health data from the system. Returns the requested resource in JSON format.

Responses

Code	Description	Response Schema
200	Successful Response	HealthResponse {status, experts_db_available}

Python example

Python

r = requests.get(f"{BASE}/api/health", headers=H).json() # {"status": "success", "experts_db_available": true}

🤖 Agents9 endpoints

POST/api/agent/listList Agents

Description

List Agents. Creates or processes a list resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token

Request Body application/json

Field	Type	Description
profile_id		Profile ID to filter agents by. If omitted, all agents are returned

Responses

Code	Description	Response Schema
200	Successful Response	—
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/agent/list", headers=H).json()

POST/api/agent/getGet Agent

Description

Get Agent. Creates or processes a get resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token

Request Body application/json

Field	Type	Description
agent_id *	string	Agent ID

Responses

Code	Description	Response Schema
200	Successful Response	—
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/agent/get", headers=H, json={"agent_id": agent_id}).json()

POST/api/agent/deleteDelete Agent

Description

Delete Agent. Creates or processes a delete resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token

Request Body application/json

Field	Type	Description
agent_id *	string	ID of agent to delete

Responses

Code	Description	Response Schema
200	Successful Response	—
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/agent/delete", headers=H, json={"agent_id": agent_id}).json()

POST/api/agent/createCreate Agent

Description

Create Agent. Creates or processes a create resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token

Request Body application/json

Field	Type	Description
provider *		Model provider
model *		Model name
name		Agent name
description		Agent description
instructions		System instructions for the agent
model_parameters		Model/provider-specific parameters
tools	array[string]	Enabled tool IDs
tool_options		Per-tool options
end_after_tools		End response generation after tool execution
hide_sequential_outputs		Hide intermediate sequential outputs
recursion_limit		Maximum recursion depth
conversation_starters		Suggested conversation starters
category		Agent category

Responses

Code	Description	Response Schema
200	Successful Response	—
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/agent/create", headers=H, json={"provider": "anthropic", "model": "claude-sonnet-4-6"}).json()

POST/api/agent/updateUpdate Agent

Description

Update Agent. Creates or processes a update resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token

Request Body application/json

Field	Type	Description
agent_id *	string	ID of agent to update
name		Agent name
description		Agent description
instructions		System instructions for the agent
model_parameters		Model/provider-specific parameters
tools		Enabled tool IDs
tool_options		Per-tool options
end_after_tools		End response generation after tool execution
hide_sequential_outputs		Hide intermediate sequential outputs
recursion_limit		Maximum recursion depth
conversation_starters		Suggested conversation starters
category		Agent category
provider		Model provider
model		Model name

Responses

Code	Description	Response Schema
200	Successful Response	—
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/agent/update", headers=H, json={"agent_id": agent_id, "name": "New Name"}).json()

POST/api/agent/export/chatsExport Chats

Description

Export Chats. Creates or processes a chats resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token

Request Body application/json

Field	Type	Description
by *
id *	string	by agent: Agent ID; by profile: Profile ID

Responses

Code	Description	Response Schema
200	Successful Response	—
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/agent/export/chats", headers=H, json={"by": "agent", "id": agent_id}).json()

POST/api/agent/export/callsExport Calls

Description

Export Calls. Creates or processes a calls resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token

Request Body application/json

Field	Type	Description
by *
id *	string	by agent: Agent ID; by profile: Profile ID
from		Optional ISO-8601 lower bound (inclusive)
to		Optional ISO-8601 upper bound (inclusive)
limit		Optional positive integer, default 200, max 1000

Responses

Code	Description	Response Schema
200	Successful Response	—
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/agent/export/calls", headers=H, json={"by": "agent", "id": agent_id}).json()

POST/api/agent/runRun Agent

Description

Run Agent. Creates or processes a run resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token

Request Body application/json

Field	Type	Description
agent_id *	string	ID of agent to run
input *		Either a plain user message string or a list of OpenResponses input items
run_timeout	number	Agent run timeout (in seconds)
previous_response_id		ID of a previous response to continue from
instructions
tools		List of tools available to the agent
tool_choice		Tool selection strategy (auto, none, or specific tool config)
temperature		Sampling temperature
max_output_tokens		Maximum number of tokens to generate
store	boolean	Whether to persist the conversation (false disables saving to /export/chats and /export/calls)

Responses

Code	Description	Response Schema
200	Successful Response	—
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/agent/run", headers={**H, "X-Agent-Id": agent_id}, json={"input": "Hello!", "store": True}).json()

🧠 Concepts5 endpoints

POST/api/concept/addAdd Concept

Description

Add a new concept (knowledge unit) with semantic embedding for long-term memory.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
text *	string	Concept text (knowledge, pattern, or learning)
api_key		API key for embeddings

Responses

Code	Description	Response Schema
200	Successful Response	AddConceptResult {status, id, text}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/concept/add", headers=H, json={"text": "Use ReportLab for PDF"}).json()

POST/api/concept/searchSearch Concepts

Description

Semantic search for concepts by meaning (not just keywords). Returns most relevant stored knowledge.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
query *	string	Search query text
limit	integer	Maximum number of results
api_key		API key for embeddings
global	boolean	Search concepts across all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	SearchConceptResult {status, results, count}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/concept/search", headers=H, json={"query": "PDF generation", "limit": 5}).json()

POST/api/concept/removeRemove Concept

Description

Remove Concept. Creates or processes a remove resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
concept_id *	integer	ID of concept to remove
global	boolean	Allow removing concepts belonging to other agents

Responses

Code	Description	Response Schema
200	Successful Response	RemoveResult {status, removed}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/concept/remove", headers=H, json={"concept_id": 42}).json()

POST/api/concept/updateUpdate Concept

Description

Update concept text and re-generate its embedding.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
concept_id *	integer	ID of concept to update
new_text *	string	New text content
api_key		API key for embeddings
global	boolean	Allow updating concepts belonging to other agents

Responses

Code	Description	Response Schema
200	Successful Response	UpdateConceptResult {status, id, text}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/concept/update", headers=H, json={"concept_id": 42, "new_text": "Updated"}).json()

POST/api/concept/listList Concepts

Description

List Concepts. Creates or processes a list resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
global	boolean	Retrieve concepts for all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	ListConceptsResult {status, results, count}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/concept/list", headers=H).json()

🎯 Defaults2 endpoints

POST/api/defaults/set_targetSet Default Target

Description

Set Default Target. Creates or processes a set_target resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token

Request Body application/json

Field	Type	Description
target *	string(uuid)

Responses

Code	Description	Response Schema
200	Successful Response	SetDefaultTargetResponse {status, target}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/defaults/set_target", headers=H, json={"target": "uuid-of-target"}).json()

POST/api/defaults/get_targetGet Default Target

Description

Get Default Target. Creates or processes a get_target resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token

Responses

Code	Description	Response Schema
200	Successful Response	GetDefaultTargetResponse {status, target}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}

Python example

Python

r = requests.post(f"{BASE}/api/defaults/get_target", headers=H).json()

⚙️ Experts10 endpoints

POST/api/experts_db/upsertUpsert Expert

Description

Insert or update an expert (without code/kwargs).

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
name *	string	Expert name
description *	string	Expert description
api_key		API key for embeddings
global	boolean	Allow modifying experts belonging to other agents

Responses

Code	Description	Response Schema
200	Successful Response	UpsertExpertResult {status, id, name, description}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/experts_db/upsert", headers=H, json={"name": "my_expert", "description": "..."}).json()

POST/api/experts_db/getGet Expert Db

Description

Get expert description only (i.e. without code/kwargs).

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
name *	string	Expert name
global	boolean	Search experts across all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	GetExpertDescriptionResult {status, id, name, description}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/experts_db/get", headers=H, json={"name": "my_expert"}).json()

POST/api/experts_db/searchSearch Experts Db

Description

Search Experts Db. Creates or processes a search resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
query *	string	Search query
limit	integer	Results limit
api_key		API key for embeddings
global	boolean	Search experts across all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	SearchExpertsDbResult {status, experts, count}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/experts_db/search", headers=H, json={"query": "telegram bot", "limit": 50}).json()

POST/api/experts_db/listList Experts

Description

Get list of all experts (blocks).

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
global	boolean	Retrieve experts for all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	ListExpertsResult {status, results, count}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/experts_db/list", headers=H).json()

POST/api/blocks/searchSearch Blocks

Description

Search Blocks. Creates or processes a search resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
query	string	Search query
limit	integer	Results limit
api_key		API key for embeddings
global	boolean	Search experts across all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	SearchBlocksResult {status, matches, total, search_time_ms}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/blocks/search", headers=H, json={"query": "send telegram", "limit": 5}).json()

POST/api/expert/saveSave Expert

Description

Save expert with code and description.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
name	string	Unique expert name (snake_case)
description	string	Expert description (in English!)
code	string	Expert code
kwargs	object	Expert parameters with defaults
cspl	string	CSPL code type
api_key		API key for embeddings
global	boolean	Allow modifying experts belonging to other agents

Responses

Code	Description	Response Schema
200	Successful Response	SaveExpertResult {status, expert_name, user_id}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/expert/save", headers=H, json={"name": "my_expert", "description": "...", "code": "...", "kwargs": {}}).json()

POST/api/expert/deleteDelete Expert

Description

Delete Expert. Creates or processes a delete resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
name *	string	Expert name
global	boolean	Allow deleting experts belonging to other agents

Responses

Code	Description	Response Schema
200	Successful Response	DeleteExpertResult {status, message}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/expert/delete", headers=H, json={"name": "my_expert"}).json()

POST/api/expert/getGet Expert

Description

Get expert info: description, code, parameters, creation date.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
name *	string	Expert name
global	boolean	Search experts across all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	GetExpertResult {status, expert_name, expert_description, expert_code, createdAt, expert_params, cspl}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/expert/get", headers=H, json={"name": "my_expert"}).json()

POST/api/expert/runRun Expert

Description

Run Expert. Creates or processes a run resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
expert_name *	string	Expert name
params	object	Expert parameters
target		ID (UUID) of the device on which the expert should run. Omit if unspecified
isolated	boolean	Isolated run in virtual environment
pin		PIN. Omit if unspecified
global	boolean	Search for this expert across all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	RunExpertResult {status, expert_name, result, task_id, execution_log, run_time_ms}
500	Internal Server Error	any
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/expert/run", headers=H, json={"expert_name": "my_expert", "params": {}}).json()

🔑 Keys & Values5 endpoints

POST/api/kv/setSet Key

Description

Set (upsert) a key-value pair with semantic embedding. Creates or updates a persistent key with optional description.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
key *	string	Unique key name
value *	string	Value to store
description	string	Optional description for semantic search
api_key		API key for embeddings
global	boolean	Allow modifying key-value pairs belonging to other agents

Responses

Code	Description	Response Schema
200	Successful Response	SetKeyResult {status, key, value, description, id}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/kv/set", headers=H, json={"key": "openai_key", "value": "sk-...", "description": "OpenAI API key"}).json()

POST/api/kv/getGet Key

Description

Get exact key-value pair by key name.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
key *	string	Exact key name to retrieve
global	boolean	Search keys across all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	GetKeyResult {status, id, key, value, description, created_at, updated_at}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/kv/get", headers=H, json={"key": "openai_key"}).json()

POST/api/kv/removeRemove Key

Description

Remove a key-value pair by key name.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
key *	string	Key name to remove
global	boolean	Allow removing key-value pairs belonging to other agents

Responses

Code	Description	Response Schema
200	Successful Response	RemoveResult {status, removed}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/kv/remove", headers=H, json={"key": "openai_key"}).json()

POST/api/kv/searchSearch Keys

Description

Semantic search across stored key-value pairs by meaning (uses pgvector embeddings).

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
query *	string	Search query
limit	integer	Maximum results
api_key		API key for embeddings
global	boolean	Search across all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	SearchKeysResult {status, results, count}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/kv/search", headers=H, json={"query": "API key GPT", "limit": 5}).json()

POST/api/kv/listList Keys

Description

List all stored key-value pairs.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
global	boolean	Retrieve key-value pairs for all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	ListKeysResult {status, results, count}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/kv/list", headers=H).json()

👤 Profiles4 endpoints

POST/api/profile/listList Profiles

Description

List Profiles. Creates or processes a list resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Responses

Code	Description	Response Schema
200	Successful Response	—
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}

Python example

Python

r = requests.post(f"{BASE}/api/profile/list", headers=H).json()

POST/api/profile/createCreate Profile

Description

Create Profile. Creates or processes a create resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
profile_name *	string	Profile name

Responses

Code	Description	Response Schema
200	Successful Response	—
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/profile/create", headers=H, json={"profile_name": "Research Team"}).json()

POST/api/profile/deleteDelete Profile

Description

Delete profile. Agents in the profile are not deleted.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
profile_id *	string	ID of profile to delete

Responses

Code	Description	Response Schema
200	Successful Response	—
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/profile/delete", headers=H, json={"profile_id": "prof_abc"}).json()

POST/api/profile/add_agentAdd Agent To Profile

Description

Add Agent To Profile. Creates or processes a add_agent resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
profile_id *	string	ID of the profile to add the agent to
agent_id *	string	ID of the agent to add

Responses

Code	Description	Response Schema
200	Successful Response	—
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/profile/add_agent", headers=H, json={"profile_id": "prof_abc", "agent_id": "agent_xyz"}).json()

📋 Rules4 endpoints

POST/api/rules/listList Rules

Description

Retrieve persistent user-defined instructions that extend the system prompt. Returned rules must be inserted into the conversation context before processing user messages and treated as additional system-level instructions. Should normally be called once at conversation startup.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
global	boolean	Retrieve rules for all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	ListRulesResult {status, results, count}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/rules/list", headers=H).json()

POST/api/rules/addAdd Rule

Description

Add a new rule (rule_id is auto-generated).

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
rule *	string	Rule text

Responses

Code	Description	Response Schema
200	Successful Response	AddRuleResult {status, rule_id, rule}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/rules/add", headers=H, json={"rule": "Always confirm destructive ops"}).json()

POST/api/rules/removeRemove Rule

Description

Remove Rule. Creates or processes a remove resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
rule_id *	string	ID of rule to remove
global	boolean	Allow removing rules belonging to other agents

Responses

Code	Description	Response Schema
200	Successful Response	RemoveResult {status, removed}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/rules/remove", headers=H, json={"rule_id": "22784"}).json()

POST/api/rules/updateUpdate Rule

Description

Update Rule. Creates or processes a update resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
rule_id *	string	ID of rule to update
rule *	string	Rule text
global	boolean	Allow updating rules belonging to other agents

Responses

Code	Description	Response Schema
200	Successful Response	UpdateRuleResult {status, rule_id, rule}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/rules/update", headers=H, json={"rule_id": "22784", "rule": "Updated text"}).json()

💻 Targets5 endpoints

POST/api/targets/listList Targets

Description

List Targets. Creates or processes a list resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
global	boolean	Retrieve targets for all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	ListTargetsResult {status, results, count}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/targets/list", headers=H).json()

POST/api/targets/addAdd Target

Description

Add a new target with description for semantic search.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
target *	string(uuid)
description *	string	Human-readable description
api_key		API key for embeddings

Responses

Code	Description	Response Schema
200	Successful Response	AddTargetResult {status, id, target, description}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/targets/add", headers=H, json={"target": "uuid-of-device", "description": "Work MacBook"}).json()

POST/api/targets/removeRemove Target

Description

Remove Target. Creates or processes a remove resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
id *	string
global	boolean	Allow removing targets belonging to other agents

Responses

Code	Description	Response Schema
200	Successful Response	RemoveResult {status, removed}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/targets/remove", headers=H, json={"id": "target_record_id"}).json()

POST/api/targets/updateUpdate Target

Description

Update a target (target value and/or description).

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
id *	string
target
description
api_key		API key for embeddings
global	boolean	Allow updating targets belonging to other agents

Responses

Code	Description	Response Schema
200	Successful Response	UpdateTargetResult {status, id, target, description}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/targets/update", headers=H, json={"id": "rec_id", "description": "New description"}).json()

POST/api/targets/searchSearch Targets

Description

Semantic search targets by description.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
query *	string
limit	integer	Maximum results
api_key		API key for embeddings
global	boolean	Search targets across all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	SearchTargetsResult {status, results, count}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/targets/search", headers=H, json={"query": "laptop", "limit": 5}).json()

⏳ Tasks1 endpoint

POST/api/tasks/checkCheck Task

Description

Check Task. Creates or processes a check resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

No auth required

Request Body application/json

Field	Type	Description
task_id *	string(uuid)

Responses

Code	Description	Response Schema
200	Successful Response	CheckTaskResult {task_id, status, result}
500	Internal Server Error	Error {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

# 1. Launch async expert resp = requests.post(f"{BASE}/api/expert/run", headers=H, json={"expert_name": "task", "wait": False}).json() task_id = resp["task_id"] # 2. Check status r = requests.post(f"{BASE}/api/tasks/check", headers=H, json={"task_id": task_id}).json()

🔐 Tokens4 endpoints

POST/api/token/generateGenerate Token

Description

Generate a new API token for user authentication.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
name	string	Optional friendly name for the token

Responses

Code	Description	Response Schema
200	Successful Response	GenerateTokenResult {status, token, user_id, name}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/token/generate", headers=H, json={"name": "Production API"}).json()

POST/api/token/validateValidate Token

Description

Validate a token and get associated user_id.

No auth required

Request Body application/json

Field	Type	Description
token *	string	Token string to validate

Responses

Code	Description	Response Schema
200	Successful Response	any
500	Internal Server Error	Error {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

# No auth header required r = requests.post(f"{BASE}/api/token/validate", json={"token": "a1b2c3d4-..."}).json()

POST/api/token/listList Tokens

Description

List Tokens. Creates or processes a list resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
global	boolean	Retrieve tokens for all agents instead of only the current agent

Responses

Code	Description	Response Schema
200	Successful Response	ListTokensResult {status, tokens, count}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/token/list", headers=H).json()

POST/api/token/revokeRevoke Token

Description

Revoke Token. Creates or processes a revoke resource. The request body must be provided as JSON with the required fields. On success, returns the created or processed object with a status field.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id

Request Body application/json

Field	Type	Description
token *	string	Token string to revoke
global	boolean	Allow revoking tokens belonging to other agents

Responses

Code	Description	Response Schema
200	Successful Response	RevokeTokenResult {status, revoked}
500	Internal Server Error	Error {status, message}
401	Unauthorized	AuthenticationRequiredError {status, message}
400	Bad Request	BadRequestError {status, message}
422	Validation Error	HTTPValidationError {detail}

Python example

Python

r = requests.post(f"{BASE}/api/token/revoke", headers=H, json={"token": "a1b2c3d4-..."}).json()

Data Models

Schemas (Models)

106 data models from docx v0.7.0 — grouped by type. Required fields marked ✓.

📤 Request Bodies45 schemas

AddAgentToProfileRequestPOST /api/profile/add_agent

Field	Type	Description
profile_id ✓	string	ID of the profile
agent_id ✓	string	ID of the agent to add

AddConceptRequestPOST /api/concept/add

Field	Type	Description
text ✓	string	Concept text (knowledge, pattern, or learning)
api_key		API key for embeddings

AddRuleRequestPOST /api/rules/add

Field	Type	Description
rule ✓	string	Rule text

AddTargetRequestPOST /api/targets/add

Field	Type	Description
target ✓	string(uuid)
description ✓	string	Human-readable description
api_key		API key for embeddings

CheckTaskRequestPOST /api/tasks/check

Field	Type	Description
task_id ✓	string(uuid)

CreateAgentRequestPOST /api/agent/create

Field	Type	Description
provider ✓		Model provider
model ✓		Model name
name		Agent name
description		Agent description
instructions		System instructions for the agent
model_parameters		Model/provider-specific parameters
tools	array[string]	Enabled tool IDs
tool_options		Per-tool options
end_after_tools		End response generation after tool execution
hide_sequential_outputs		Hide intermediate sequential outputs
recursion_limit		Maximum recursion depth
conversation_starters		Suggested conversation starters
category		Agent category

CreateProfileRequestPOST /api/profile/create

Field	Type	Description
profile_name ✓	string	Profile name

DeleteAgentRequestPOST /api/agent/delete

Field	Type	Description
agent_id ✓	string	ID of agent to delete

DeleteExpertRequestPOST /api/expert/delete

Field	Type	Description
name ✓	string	Expert name
global	boolean	Allow deleting experts belonging to other agents

DeleteProfileRequestPOST /api/profile/delete

Field	Type	Description
profile_id ✓	string	ID of profile to delete

ExportCallsRequestPOST /api/agent/export/calls

Field	Type	Description
by ✓
id ✓	string	by agent: Agent ID; by profile: Profile ID
from		Optional ISO-8601 lower bound (inclusive)
to		Optional ISO-8601 upper bound (inclusive)
limit		Optional positive integer, default 200, max 1000

ExportChatsRequestPOST /api/agent/export/chats

Field	Type	Description
by ✓
id ✓	string	by agent: Agent ID; by profile: Profile ID

GenerateTokenRequestPOST /api/token/generate

Field	Type	Description
name	string	Optional friendly name for the token

GetAgentRequestPOST /api/agent/get

Field	Type	Description
agent_id ✓	string	Agent ID

GetExpertRequestPOST /api/expert/get & /api/experts_db/get

Field	Type	Description
name ✓	string	Expert name
global	boolean	Search experts across all agents instead of only the current agent

GetKeyRequestPOST /api/kv/get

Field	Type	Description
key ✓	string	Exact key name to retrieve
global	boolean	Search keys across all agents instead of only the current agent

ListAgentsRequestPOST /api/agent/list

Field	Type	Description
profile_id		Profile ID to filter agents by. If omitted, all agents are returned

ListConceptsRequestPOST /api/concept/list

Field	Type	Description
global	boolean	Retrieve concepts for all agents instead of only the current agent

ListExpertsRequestPOST /api/experts_db/list

Field	Type	Description
global	boolean	Retrieve experts for all agents instead of only the current agent

ListKeysRequestPOST /api/kv/list

Field	Type	Description
global	boolean	Retrieve key-value pairs for all agents instead of only the current agent

ListRulesRequestPOST /api/rules/list

Field	Type	Description
global	boolean	Retrieve rules for all agents instead of only the current agent

ListTargetsRequestPOST /api/targets/list

Field	Type	Description
global	boolean	Retrieve targets for all agents instead of only the current agent

ListTokensRequestPOST /api/token/list

Field	Type	Description
global	boolean	Retrieve tokens for all agents instead of only the current agent

RemoveConceptRequestPOST /api/concept/remove

Field	Type	Description
concept_id ✓	integer	ID of concept to remove
global	boolean	Allow removing concepts belonging to other agents

RemoveExpertRequestPOST /api/experts_db/remove

Field	Type	Description
name ✓	string	Expert name
global	boolean	Allow removing experts belonging to other agents

RemoveKeyRequestPOST /api/kv/remove

Field	Type	Description
key ✓	string	Key name to remove
global	boolean	Allow removing key-value pairs belonging to other agents

RemoveRuleRequestPOST /api/rules/remove

Field	Type	Description
rule_id ✓	string	ID of rule to remove
global	boolean	Allow removing rules belonging to other agents

RemoveTargetRequestPOST /api/targets/remove

Field	Type	Description
id ✓	string
global	boolean	Allow removing targets belonging to other agents

RevokeTokenRequestPOST /api/token/revoke

Field	Type	Description
token ✓	string	Token string to revoke
global	boolean	Allow revoking tokens belonging to other agents

RunAgentRequestPOST /api/agent/run

Field	Type	Description
agent_id ✓	string	ID of agent to run
input ✓		Plain user message or list of OpenResponses input items
run_timeout	number	Agent run timeout in seconds
previous_response_id		ID of a previous response to continue from
instructions
tools		List of tools available to the agent
tool_choice		Tool selection strategy: auto, none, or specific
temperature		Sampling temperature
max_output_tokens		Maximum number of tokens to generate
store	boolean	Whether to persist the conversation

RunExpertRequestPOST /api/expert/run

Field	Type	Description
expert_name ✓	string	Expert name
params	object	Expert parameters
target		ID (UUID) of the device. Omit if unspecified
isolated	boolean	Isolated run in virtual environment
pin		PIN. Omit if unspecified
global	boolean	Search for this expert across all agents

SaveExpertRequestPOST /api/expert/save

Field	Type	Description
name	string	Unique expert name (snake_case)
description	string	Expert description (in English!)
code	string	Expert code
kwargs	object	Expert parameters with defaults
cspl	string	CSPL code type
api_key		API key for embeddings
global	boolean	Allow modifying experts belonging to other agents

SearchBlocksRequestPOST /api/blocks/search

Field	Type	Description
query	string	Search query
limit	integer	Results limit
api_key		API key for embeddings
global	boolean	Search experts across all agents

SearchConceptRequestPOST /api/concept/search

Field	Type	Description
query ✓	string	Search query text
limit	integer	Maximum number of results
api_key		API key for embeddings
global	boolean	Search concepts across all agents

SearchExpertsRequestPOST /api/experts_db/search

Field	Type	Description
query ✓	string	Search query
limit	integer	Results limit
api_key		API key for embeddings
global	boolean	Search experts across all agents

SearchKeyRequestPOST /api/kv/search

Field	Type	Description
query ✓	string	Search query
limit	integer	Maximum results
api_key		API key for embeddings
global	boolean	Search across all agents

SearchTargetsRequestPOST /api/targets/search

Field	Type	Description
query ✓	string
limit	integer	Maximum results
api_key		API key for embeddings
global	boolean	Search targets across all agents

SetDefaultTargetRequestPOST /api/defaults/set_target

Field	Type	Description
target ✓	string(uuid)

SetKeyRequestPOST /api/kv/set

Field	Type	Description
key ✓	string	Unique key name
value ✓	string	Value to store
description	string	Optional description for semantic search
api_key		API key for embeddings
global	boolean	Allow modifying key-value pairs belonging to other agents

UpdateAgentRequestPOST /api/agent/update

Field	Type	Description
agent_id ✓	string	ID of agent to update
name		Agent name
description		Agent description
instructions		System instructions for the agent
model_parameters		Model/provider-specific parameters
tools		Enabled tool IDs
tool_options		Per-tool options
end_after_tools		End response generation after tool execution
hide_sequential_outputs		Hide intermediate sequential outputs
recursion_limit		Maximum recursion depth
conversation_starters		Suggested conversation starters
category		Agent category
provider		Model provider
model		Model name

UpdateConceptRequestPOST /api/concept/update

Field	Type	Description
concept_id ✓	integer	ID of concept to update
new_text ✓	string	New text content
api_key		API key for embeddings
global	boolean	Allow updating concepts belonging to other agents

UpdateRuleRequestPOST /api/rules/update

Field	Type	Description
rule_id ✓	string	ID of rule to update
rule ✓	string	Rule text
global	boolean	Allow updating rules belonging to other agents

UpdateTargetRequestPOST /api/targets/update

Field	Type	Description
id ✓	string
target
description
api_key		API key for embeddings
global	boolean	Allow updating targets belonging to other agents

UpsertExpertRequestPOST /api/experts_db/upsert

Field	Type	Description
name ✓	string	Expert name
description ✓	string	Expert description
api_key		API key for embeddings
global	boolean	Allow modifying experts belonging to other agents

ValidateTokenRequestPOST /api/token/validate

Field	Type	Description
token ✓	string	Token string to validate

📥 Response Bodies36 schemas

AddConceptResult200 /api/concept/add

Field	Type	Description
status	string
id ✓	integer
text ✓	string

AddRuleResult200 /api/rules/add

Field	Type	Description
status	string
rule_id ✓	string	ID of added rule
rule ✓	string	Rule text

AddTargetResult200 /api/targets/add

Field	Type	Description
status	string
id ✓	string(uuid)
target ✓	string
description ✓	string	Target description

CheckTaskResult200 /api/tasks/check

Field	Type	Description
task_id ✓	string(uuid)
status ✓		Task status
result ✓		completed: task result; error: error message

DeleteExpertResult200 /api/expert/delete

Field	Type	Description
status	string
message ✓	string

GenerateTokenResult200 /api/token/generate

Field	Type	Description
status	string
token ✓	string	Generated token string
user_id ✓	string
name ✓	string	Friendly name for the token

GetDefaultTargetResponse200 /api/defaults/get_target

Field	Type	Description
status	string
target ✓

GetExpertDescriptionResult200 /api/experts_db/get

Field	Type	Description
status	string
id ✓	integer
name ✓	string	Expert name
description ✓	string	Expert description

GetExpertResult200 /api/expert/get

Field	Type	Description
status	string
expert_name ✓	string	Expert name
expert_description ✓	string
expert_code ✓	string
createdAt ✓	string(date-time)
expert_prompt ✓	string
expert_params ✓	object	Expert parameters with defaults
cspl ✓	string	CSPL code type

GetKeyResult200 /api/kv/get

Field	Type	Description
status	string
id ✓	integer
key ✓	string	Key name
value ✓	string	Value
description ✓	string	Description for semantic search
created_at ✓	string(date-time)
updated_at ✓	string(date-time)

HealthResponse200 /api/health

Field	Type	Description
status	string
experts_db_available ✓	boolean

InvalidTokenResult401 /api/token/validate

Field	Type	Description
status	string
valid	boolean

ListConceptsResult200 /api/concept/list

Field	Type	Description
status	string
results ✓	array[ListConceptResult]
count ✓	integer

ListExpertsResult200 /api/experts_db/list

Field	Type	Description
status	string
results ✓	array[ExpertResult]
count ✓	integer

ListKeysResult200 /api/kv/list

Field	Type	Description
status	string
results ✓	array[ListKeyResult]
count ✓	integer

ListRulesResult200 /api/rules/list

Field	Type	Description
status	string
results ✓	array[ListRuleResult]
count ✓	integer

ListTargetsResult200 /api/targets/list

Field	Type	Description
status	string
results ✓	array[ListTargetResult]
count ✓	integer

ListTokensResult200 /api/token/list

Field	Type	Description
status	string
tokens ✓	array[ListTokenResult]
count ✓	integer

RemoveResult200 (remove endpoints)

Field	Type	Description
status	string
removed ✓	boolean

RevokeTokenResult200 /api/token/revoke

Field	Type	Description
status	string
revoked ✓	boolean

RunExpertResult200 /api/expert/run

Field	Type	Description
status	string
expert_name ✓	string	Expert name
result ✓	string
task_id		ID of the deferred expert execution task
execution_log ✓	array[string]	Log messages generated during expert execution
run_time_ms		Expert runtime in milliseconds

SaveExpertResult200 /api/expert/save

Field	Type	Description
status	string
expert_name ✓	string	Expert name
user_id ✓	string

SearchBlocksResult200 /api/blocks/search

Field	Type	Description
status	string
matches ✓	array[SearchBlockMatch]
total ✓	integer
search_time_ms ✓	number	Search time in milliseconds

SearchConceptResult200 /api/concept/search

Field	Type	Description
status	string
results ✓	array[SearchConcept]
count ✓	integer

SearchExpertsDbResult200 /api/experts_db/search

Field	Type	Description
status	string
experts ✓	array[SearchExpertDbResult]
count ✓	integer

SearchKeysResult200 /api/kv/search

Field	Type	Description
status	string
results ✓	array[SearchKeyResult]
count ✓	integer

SearchTargetsResult200 /api/targets/search

Field	Type	Description
status	string
results ✓	array[SearchTargetResult]
count ✓	integer

SetDefaultTargetResponse200 /api/defaults/set_target

Field	Type	Description
status	string
target ✓	string(uuid)

SetKeyResult200 /api/kv/set

Field	Type	Description
status	string
key ✓	string	Key name
value ✓	string	Stored value
description ✓	string	Description for semantic search
id ✓	integer

UpdateConceptResult200 /api/concept/update

Field	Type	Description
status	string
id ✓	integer	ID of updated concept
text ✓	string	New text content

UpdateRuleResult200 /api/rules/update

Field	Type	Description
status	string
rule_id ✓	string	ID of updated rule
rule ✓	string	Rule text

UpdateTargetResult200 /api/targets/update

Field	Type	Description
status	string
id ✓	string(uuid)
target ✓	string
description ✓	string	Target description

UpsertExpertResult200 /api/experts_db/upsert

Field	Type	Description
status	string
id ✓	integer
name ✓	string	Expert name
description ✓	string	Expert description

ValidTokenResult200 /api/token/validate

Field	Type	Description
status	string
valid	boolean
user_id ✓
profile_id ✓
agent_id ✓
name ✓		Friendly name for the token

⚠️ Error Schemas6 schemas

AuthenticationRequiredError401 responses

Field	Type	Description
status	string
message	string

BadRequestError400 responses

Field	Type	Description
status	string
message ✓	string	Error message

Error500 responses

Field	Type	Description
status	string
message ✓	string	Error message

HTTPValidationError422 responses

Field	Type	Description
detail	array[ValidationError]

RunExpertErrorExpert execution failure

Field	Type	Description
status	string
expert_name ✓	string	Expert name
message ✓	string	Error message
execution_log ✓	array[string]	Log messages generated during expert execution

ValidationErrorInside HTTPValidationError.detail

Field	Type	Description
loc ✓	array[]
msg ✓	string
type ✓	string
input
ctx	object

🔁 Sub-models11 schemas

ExpertResultInside ListExpertsResult.results

Field	Type	Description
id ✓	integer
name ✓	string	Expert name
description ✓	string	Expert description
created_at ✓	string(date-time)
updated_at ✓	string(date-time)
deleted_at

ListConceptResultInside ListConceptsResult.results

Field	Type	Description
concept_id ✓	integer	ID of concept
concept_text ✓	string	Concept text
created_at ✓	string(date-time)
updated_at ✓	string(date-time)

ListKeyResultInside ListKeysResult.results

Field	Type	Description
kv_id ✓	integer
kv_key ✓	string	Key name
kv_value ✓	string	Value
kv_description ✓	string	Description for semantic search
created_at ✓	string(date-time)
updated_at ✓	string(date-time)

ListRuleResultInside ListRulesResult.results

Field	Type	Description
id ✓	string
rule ✓	string	Rule text
created_at ✓	string(date-time)
updated_at ✓	string(date-time)

ListTargetResultInside ListTargetsResult.results

Field	Type	Description
id ✓	string(uuid)
target ✓	string
description ✓	string	Target description
created_at ✓	string(date-time)
updated_at ✓	string(date-time)

ListTokenResultInside ListTokensResult.tokens

Field	Type	Description
token ✓	string	Token string
name ✓	string	Friendly name for the token
created_at ✓	string(date-time)

SearchBlockMatchInside SearchBlocksResult.matches

Field	Type	Description
name ✓	string	Expert name
description ✓	string	Expert description
score ✓	integer	Percentage of match
kwargs ✓	object	Expert parameters with defaults
code ✓	string	Expert code

SearchConceptInside SearchConceptResult.results

Field	Type	Description
concept_id ✓	integer	ID of concept
concept_text ✓	string	Concept text
similarity ✓	number	Semantic similarity score (0.0 to 1.0)
created_at ✓	string(date-time)

SearchExpertDbResultInside SearchExpertsDbResult.experts

Field	Type	Description
id ✓	integer
name ✓	string	Expert name
description ✓	string	Expert description
code ✓	string	Expert code
kwargs ✓	object	Expert parameters with defaults
similarity ✓	number	Semantic similarity score between the query and name+description (0.0 to 1.0)

SearchKeyResultInside SearchKeysResult.results

Field	Type	Description
kv_id ✓	integer
kv_key ✓	string	Key name
kv_value ✓	string	Value
kv_description ✓	string	Description for semantic search
similarity ✓	number	Semantic similarity score between the query and key+value+description (0.0 to 1.0)
created_at ✓	string(date-time)
updated_at ✓	string(date-time)

SearchTargetResultInside SearchTargetsResult.results

Field	Type	Description
id ✓	string(uuid)
target ✓	string
description ✓	string	Target description
similarity ✓	number	Semantic similarity score between query and target+description (0.0 to 1.0)

👥 Shared / Utility8 schemas

GenericContentPartContent part in MessageItem

Field	Type	Description
type ✓	string

GenericItemInput item in RunAgentRequest

Field	Type	Description
type ✓	string

MessageItemMessage in conversation input

Field	Type	Description
type ✓	string
role ✓
content ✓

ModelParametersNested in Create/UpdateAgentRequest

Field	Type	Description
temperature		openAI, azureOpenAI, google, anthropic, bedrock — controls determinism
presence_penalty		openAI, azureOpenAI — penalty for repetitive tokens
frequency_penalty		openAI, azureOpenAI — penalty for repeated tokens
stop		openAI, azureOpenAI — stop tokens
top_p		openAI, azureOpenAI — nucleus sampling (0-1)
topP		google, anthropic — nucleus sampling
topK		google, anthropic — limits next token selection to top K
max_tokens		openAI, azureOpenAI — maximum tokens in model response
maxOutputTokens		google, anthropic — maximum tokens in response
promptCache		anthropic, bedrock — enables/disables built-in prompt caching
reasoning_effort		openAI, azureOpenAI, bedrock — controls reasoning effort level
reasoning_summary		openAI, azureOpenAI — sets reasoning summary preferences
useResponsesApi		openAI, azureOpenAI — enables/disables responses API
verbosity		openAI, azureOpenAI — controls verbosity level
web_search		openAI, azureOpenAI, google, anthropic — enables/disables web search
disableStreaming		openAI, azureOpenAI — disables streaming responses
thinkingBudget		google, anthropic, bedrock — controls number of thinking tokens
thinkingLevel		google Gemini 3+ — controls thinking effort level
effort		anthropic, bedrock — controls Adaptive Thinking effort level
thinkingDisplay		anthropic, bedrock — controls whether reasoning content is returned
thinking		google, anthropic, bedrock — whether model should think before responding
region		bedrock — AWS region for Amazon Bedrock endpoints
maxTokens		bedrock — maximum output tokens for Amazon Bedrock
resendFiles		Resend all previously attached files
imageDetail		Vision requests resolution: low, auto, high
fileTokenLimit		Set maximum token limit for file processing

ToolIn RunAgentRequest.tools

Field	Type	Description
type ✓	string
name ✓	string
description ✓	string
parameters

ToolOptionsSchemaPer-tool options

Field	Type	Description
defer_loading		Defer tool loading until first use
allowed_callers		Allowed caller types

ToolParametersInside Tool.parameters

Field	Type	Description
type ✓	string
properties
required

ToolPropertyInside ToolParameters.properties

Field	Type	Description
type ✓	string
description

Other APIs return responses.
We return Agents,
who come in Teams.

All 48 endpoints

Schemas (Models)

Everything you need to ship fast.

Ready to build?

Other APIs return responses.We return Agents,who come in Teams.

All 48 endpoints

Schemas (Models)

Everything you need to ship fast.

Ready to build?

Other APIs return responses.
We return Agents,
who come in Teams.