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

64 documented endpoints across 14 sections. Exact request fields, per-endpoint response codes and schemas from docx v1.2.3.

View API Docs →
64 endpoints
14 sections
148 schemas
quickstart.py
import requests BASE = "https://api.extella.ai" TOKEN = "your-token-uuid" H = {"X-Auth-Token": TOKEN} # 1. Create an agent a = requests.post(f"{BASE}/api/agent/create", headers=H, json={"name": "Researcher", "provider": "anthropic"}).json() # 2. Run it r = requests.post(f"{BASE}/api/agent/run", headers=H, json={"agent_id": a["id"], "input": "Hello!"}) ✓ {"response_id":"resp_xyz","answer":"Hi!"}
64
API endpoints
14
API sections
60/min
Rate limit per IP
Pro
Full access plan
Reference — v1.2.3

All 64 endpoints

v1.2.3 — 14 sections — 64 endpoints. Each card: verbatim description, exact request fields (* = required), per-endpoint response table, Python example.

⚡ General1 endpoint
GET/api/healthHealth Check
Description

Health check.

Responses
CodeDescriptionResponse Schema
200Successful ResponseHealthResponse {experts_db_available, status}
Python example
Python
r = requests.get(f"{BASE}/api/health", headers=H).json()
🤖 Agents9 endpoints
POST/api/agent/createCreate Agent
Description

Create agent.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
apiKeystringAPI key used to authenticate requests to the custom provider—
baseURLstringBase URL for the custom provider API endpoint—
categorystringAgent category—
conversation_startersarray[string]Suggested conversation starters—
descriptionstringAgent description—
end_after_toolsbooleanEnd response generation after tool execution—
hide_sequential_outputsbooleanHide intermediate sequential outputs—
instructionsstringSystem instructions for the agent—
model *stringModel name—
model_parametersModelParametersModel/provider-specific parameters—
namestringAgent name—
provider *stringModel provider—
recursion_limitintegerMaximum recursion depth—
tool_optionsobjectPer-tool options—
toolsarray[string]Enabled tool IDs—
Responses
CodeDescriptionResponse Schema
200Successful Response—
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/agent/create", headers=H, json={ "provider": "custom", "model": "model" }).json()
POST/api/agent/deleteDelete Agent
Description

Delete agent.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
agent_id *stringID of agent to delete—
Responses
CodeDescriptionResponse Schema
200Successful Response—
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/agent/delete", headers=H, json={ "agent_id": "agent_..." }).json()
POST/api/agent/export/callsExport Calls
Description

Export calls.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
by *string—
fromstringOptional ISO-8601 lower bound (inclusive)—
id *stringby agent: Agent ID; by profile: Profile ID—
limitintegerOptional positive integer, default 200, max 1000—
tostringOptional ISO-8601 upper bound (inclusive)—
Responses
CodeDescriptionResponse Schema
200Successful Response—
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/agent/export/calls", headers=H, json={ "by": "agent", "id": "id" }).json()
POST/api/agent/export/chatsExport Chats
Description

Export chats.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
by *string—
id *stringby agent: Agent ID; by profile: Profile ID—
Responses
CodeDescriptionResponse Schema
200Successful Response—
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/agent/export/chats", headers=H, json={ "by": "agent", "id": "id" }).json()
POST/api/agent/getGet Agent
Description

Get basic agent info.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
agent_id *stringAgent ID—
Responses
CodeDescriptionResponse Schema
200Successful Response—
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/agent/get", headers=H, json={ "agent_id": "agent_..." }).json()
POST/api/agent/get_currentGet Current
Description

Get current profile ID and agent ID.

Responses
CodeDescriptionResponse Schema
200Successful ResponseGetCurrentAgentResponse {agent_id, profile_id}
400Bad RequestBadRequestError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/agent/get_current", headers=H).json()
POST/api/agent/listList Agents
Description

List agents.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
profile_idstringProfile ID to filter agents by. If omitted, all agents are returned—
Responses
CodeDescriptionResponse Schema
200Successful Response—
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/agent/list", headers=H).json()
POST/api/agent/runRun Agent
Description

Run agent (non-streaming).

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
agent_id *stringID of agent to run—
input *array | stringEither a plain user message string or a list of OpenResponses input items—
instructionsstring—
max_output_tokensintegerMaximum number of tokens to generate—
previous_response_idstringID of a previous response to continue from—
run_timeoutnumberAgent run timeout (in seconds)120
storebooleanWhether to persist the conversation (false disables saving to /export/chats and /export/calls)True
temperaturenumberSampling temperature—
tool_choiceobject | stringTool selection strategy (auto, none, or specific tool config)—
toolsarray[Tool]List of tools available to the agent—
Responses
CodeDescriptionResponse Schema
200Successful Response—
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/agent/run", headers=H, json={ "agent_id": "agent_...", "input": "Hello! Briefly introduce yourself." }).json()
POST/api/agent/updateUpdate Agent
Description

Update agent.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
agent_id *stringID of agent to update—
apiKeystringAPI key used to authenticate requests to the custom provider—
baseURLstringBase URL for the custom provider API endpoint—
categorystringAgent category—
conversation_startersarray[string]Suggested conversation starters—
descriptionstringAgent description—
end_after_toolsbooleanEnd response generation after tool execution—
hide_sequential_outputsbooleanHide intermediate sequential outputs—
instructionsstringSystem instructions for the agent—
modelstringModel name—
model_parametersModelParametersModel/provider-specific parameters—
namestringAgent name—
providerstringModel provider—
recursion_limitintegerMaximum recursion depth—
tool_optionsobjectPer-tool options—
toolsarray[string]Enabled tool IDs—
Responses
CodeDescriptionResponse Schema
200Successful Response—
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/agent/update", headers=H, json={ "agent_id": "agent_..." }).json()
🧠 Concepts5 endpoints
POST/api/concept/addAdd Concept
Description

Add 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
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
globalbooleanConcept is globalFalse
text *stringConcept text (knowledge, pattern, or learning)—
Responses
CodeDescriptionResponse Schema
200Successful ResponseAddConceptResult {id, status, text}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/concept/add", headers=H, json={ "text": "Use ReportLab for PDF generation in Docker" }).json()
POST/api/concept/deleteDelete Concept
Description

Delete concept.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
concept_id *integerID of concept to delete—
Responses
CodeDescriptionResponse Schema
200Successful ResponseDeleteResult {deleted, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/concept/delete", headers=H, json={ "concept_id": 0 }).json()
POST/api/concept/listList Concepts
Description

Get list of concepts.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
globalbooleanRetrieve also global conceptsFalse
limitintegerMax results—
offsetintegerPagination offset0
Responses
CodeDescriptionResponse Schema
200Successful ResponseListConceptsResult {count, results, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/concept/list", headers=H).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
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
globalbooleanSearch also across global conceptsFalse
limitintegerMaximum number of results5
query *stringSearch query text—
Responses
CodeDescriptionResponse Schema
200Successful ResponseSearchConceptsResult {count, results, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/concept/search", headers=H, json={ "query": "PDF generation libraries" }).json()
POST/api/concept/updateUpdate Concept
Description

Update existing concept.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
concept_id *integerID of concept to update—
new_text *stringNew text content—
Responses
CodeDescriptionResponse Schema
200Successful ResponseUpdateConceptResult {id, status, text}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/concept/update", headers=H, json={ "concept_id": 0, "new_text": "new_text" }).json()
🎯 Defaults2 endpoints
POST/api/defaults/get_targetGet Default Target
Description

Get default target.

Headers: X-Auth-Token
Responses
CodeDescriptionResponse Schema
200Successful ResponseGetDefaultTargetResponse {status, target}
401UnauthorizedAuthenticationRequiredError {message, status}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/defaults/get_target", headers=H).json()
POST/api/defaults/set_targetSet Default Target
Description

Set default target.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
target *string(uuid)—
Responses
CodeDescriptionResponse Schema
200Successful ResponseSetDefaultTargetResponse {status, target}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/defaults/set_target", headers=H, json={ "target": "uuid-of-target" }).json()
⚙️ Experts9 endpoints
POST/api/expert/deleteDelete Expert
Description

Delete expert.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
name *stringExpert name—
Responses
CodeDescriptionResponse Schema
200Successful ResponseDeleteExpertResult {message, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/expert/delete", headers=H, json={ "name": "pdf_to_text" }).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
FieldTypeDescriptionDefault
globalbooleanSearch also across global expertsFalse
name *stringExpert name—
Responses
CodeDescriptionResponse Schema
200Successful ResponseGetExpertResult {createdAt, cspl, expert_code, expert_description, expert_name, expert_params, expert_prompt, global, group_name, status, updatedAt}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/expert/get", headers=H, json={ "name": "pdf_to_text" }).json()
POST/api/expert/listList Experts
Description

Get list of experts.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
globalbooleanRetrieve also global expertsFalse
limitintegerMax results—
offsetintegerPagination offset0
Responses
CodeDescriptionResponse Schema
200Successful ResponseListExpertsResult {count, results, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/expert/list", headers=H).json()
POST/api/expert/removeRemove Expert
Description

Remove expert to trash.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
name *stringExpert name—
Responses
CodeDescriptionResponse Schema
200Successful ResponseRemoveResult {removed, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/expert/remove", headers=H, json={ "name": "pdf_to_text" }).json()
POST/api/expert/runRun Expert
Description

Run expert.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
expert_name *stringExpert name—
globalbooleanSearch also across global expertsFalse
isolatedbooleanIsolated run in virtual environmentFalse
paramsobjectExpert parameters—
pinstringPIN. Omit if unspecified—
targetstringID (UUID) of the device on which the expert should run. Omit if unspecified—
waitbooleanWhether to wait for the task to complete before returning a responseTrue
Responses
CodeDescriptionResponse Schema
200Successful ResponseRunExpertCompleteResult {execution_log, expert_name, result, run_time_ms, status} / RunExpertDeferredResult {execution_log, expert_name, result, status, task_id}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status} / RunExpertError {execution_log, expert_name, message, status}
Python example
Python
r = requests.post(f"{BASE}/api/expert/run", headers=H, json={ "expert_name": "pdf_to_text" }).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
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
code *stringExpert code—
csplstringCSPL code typefython
description *stringExpert description (in English!)—
globalbooleanExpert is globalFalse
kwargsobjectExpert parameters with defaults—
name *stringUnique expert name (snake_case)—
Responses
CodeDescriptionResponse Schema
200Successful ResponseSaveExpertResult {expert_name, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/expert/save", headers=H, json={ "name": "pdf_to_text", "description": "Extract text from PDF files", "code": "def pdf_to_text(...)..." }).json()
POST/api/expert/searchSearch Experts
Description

Semantic search for experts.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
globalbooleanSearch also global expertsFalse
limitintegerResults limit10
query *stringSearch query—
Responses
CodeDescriptionResponse Schema
200Successful ResponseSearchExpertsResult {count, experts, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/expert/search", headers=H, json={ "query": "convert PDF to text" }).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
FieldTypeDescriptionDefault
globalbooleanSearch also across global expertsFalse
name *stringExpert name—
Responses
CodeDescriptionResponse Schema
200Successful ResponseGetExpertDescriptionResult {description, global, group_name, id, name, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/experts_db/get", headers=H, json={ "name": "pdf_to_text" }).json()
POST/api/experts_db/upsertUpsert Expert
Description

Insert or update expert (without code/kwargs).

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
description *stringExpert description—
name *stringExpert name—
Responses
CodeDescriptionResponse Schema
200Successful ResponseUpsertExpertResult {description, id, name, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/experts_db/upsert", headers=H, json={ "name": "pdf_to_text", "description": "Extract text from PDF files" }).json()
🔑 Keys & Values5 endpoints
POST/api/kv/deleteDelete Key
Description

Delete key-value pair.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
key *stringKey name to delete—
Responses
CodeDescriptionResponse Schema
200Successful ResponseDeleteResult {deleted, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/kv/delete", headers=H, json={ "key": "key" }).json()
POST/api/kv/getGet Kv
Description

Get key-value pair by key name.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
globalbooleanSearch also across global keysFalse
key *stringExact key name to retrieve—
Responses
CodeDescriptionResponse Schema
200Successful ResponseGetKeyResult {created_at, description, global, id, key, status, updated_at, value}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/kv/get", headers=H, json={ "key": "openai_key" }).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
FieldTypeDescriptionDefault
globalbooleanRetrieve also global key-value pairsFalse
Responses
CodeDescriptionResponse Schema
200Successful ResponseListKeysResult {count, results, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/kv/list", headers=H).json()
POST/api/kv/searchSearch Keys
Description

Semantic search across stored key-value pairs by meaning.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
globalbooleanSearch also across global keysFalse
limitintegerMaximum results5
query *stringSearch query—
Responses
CodeDescriptionResponse Schema
200Successful ResponseSearchKeysResult {count, results, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/kv/search", headers=H, json={ "query": "my OpenAI key" }).json()
POST/api/kv/setSet Kv
Description

Create or update a key-value pair with semantic embedding.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
descriptionstringOptional description for semantic search
globalbooleanKey-value pair is globalFalse
key *stringUnique key name—
value *stringValue to store—
Responses
CodeDescriptionResponse Schema
200Successful ResponseSetKeyResult {description, id, key, status, value}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/kv/set", headers=H, json={ "key": "openai_key", "value": "sk-proj-..." }).json()
👤 Profiles4 endpoints
POST/api/profile/add_agentAdd Agent To Profile
Description

Add agent to profile.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
agent_id *stringID of the agent to add—
profile_id *stringID of the profile to add the agent to—
Responses
CodeDescriptionResponse Schema
200Successful Response—
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/profile/add_agent", headers=H, json={ "profile_id": "team_...", "agent_id": "agent_..." }).json()
POST/api/profile/createCreate Profile
Description

Create profile.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
profile_name *stringProfile name—
Responses
CodeDescriptionResponse Schema
200Successful Response—
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/profile/create", headers=H, json={ "profile_name": "Test Profile" }).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
FieldTypeDescriptionDefault
profile_id *stringID of profile to delete—
Responses
CodeDescriptionResponse Schema
200Successful Response—
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/profile/delete", headers=H, json={ "profile_id": "team_..." }).json()
POST/api/profile/listList Profiles
Description

List all profiles.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Responses
CodeDescriptionResponse Schema
200Successful Response—
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/profile/list", headers=H).json()
📋 Rules4 endpoints
POST/api/rules/addAdd Rule
Description

Add new rule.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
globalbooleanRule is globalFalse
rule *stringRule text—
Responses
CodeDescriptionResponse Schema
200Successful ResponseAddRuleResult {rule, rule_id, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/rules/add", headers=H, json={ "rule": "Always use Python type hints" }).json()
POST/api/rules/deleteDelete Rule
Description

Delete rule.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
rule_id *stringID of rule to delete—
Responses
CodeDescriptionResponse Schema
200Successful ResponseDeleteResult {deleted, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/rules/delete", headers=H, json={ "rule_id": "0" }).json()
POST/api/rules/listList Rules
Description

Get list of rules.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
globalbooleanRetrieve also global rulesFalse
Responses
CodeDescriptionResponse Schema
200Successful ResponseListRulesResult {count, results, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/rules/list", headers=H).json()
POST/api/rules/updateUpdate Rule
Description

Update existing rule.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
rule *stringRule text—
rule_id *stringID of rule to update—
Responses
CodeDescriptionResponse Schema
200Successful ResponseUpdateRuleResult {rule, rule_id, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/rules/update", headers=H, json={ "rule_id": "0", "rule": "Always use Python type hints" }).json()
💻 Targets5 endpoints
POST/api/targets/addAdd Target
Description

Add new target with description for semantic search.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
description *stringHuman-readable description—
globalbooleanTarget is globalFalse
target *string(uuid)—
Responses
CodeDescriptionResponse Schema
200Successful ResponseAddTargetResult {description, id, status, target}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/targets/add", headers=H, json={ "target": "uuid-of-target", "description": "John's work laptop" }).json()
POST/api/targets/deleteDelete Target
Description

Delete target.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
id *string(uuid)—
Responses
CodeDescriptionResponse Schema
200Successful ResponseDeleteResult {deleted, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/targets/delete", headers=H, json={ "id": "uuid-of-target" }).json()
POST/api/targets/listList Targets
Description

Get list of targets.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
globalbooleanRetrieve also global targetsFalse
Responses
CodeDescriptionResponse Schema
200Successful ResponseListTargetsResult {count, results, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/targets/list", headers=H).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
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
globalbooleanSearch also across global targetsFalse
limitintegerMaximum results5
query *string—
Responses
CodeDescriptionResponse Schema
200Successful ResponseSearchTargetsResult {count, results, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/targets/search", headers=H, json={ "query": "laptop for development" }).json()
POST/api/targets/updateUpdate Target
Description

Update target value and/or description.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
descriptionstring—
id *string—
targetstring—
Responses
CodeDescriptionResponse Schema
200Successful ResponseUpdateTargetResult {description, id, status, target}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/targets/update", headers=H, json={ "id": "id" }).json()
🔗 Pipelines7 endpoints
POST/api/pipeline/deleteDelete Pipeline
Description

Delete pipeline.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
name *stringPipeline name—
Responses
CodeDescriptionResponse Schema
200Successful ResponseDeletePipelineResult {message, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/pipeline/delete", headers=H, json={ "name": "my_pipeline" }).json()
POST/api/pipeline/getGet Pipeline
Description

Get pipeline info: description, blocks, connections, advanced_settings, creation date.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
globalbooleanSearch also across global pipelinesFalse
name *stringPipeline name—
Responses
CodeDescriptionResponse Schema
200Successful ResponseGetPipelineFullResult {advanced_settings, blocks, connections, created_at, description, global, id, name, status, updated_at}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/pipeline/get", headers=H, json={ "name": "my_pipeline" }).json()
POST/api/pipeline/listList Pipelines
Description

Get list of pipelines.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
globalbooleanRetrieve also global pipelinesFalse
limitintegerMax results—
offsetintegerPagination offset0
Responses
CodeDescriptionResponse Schema
200Successful ResponseListPipelinesResult {count, results, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/pipeline/list", headers=H).json()
POST/api/pipeline/removeRemove Pipeline
Description

Remove pipeline to trash.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
name *stringExpert name—
Responses
CodeDescriptionResponse Schema
200Successful ResponseRemoveResult {removed, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/pipeline/remove", headers=H, json={ "name": "pdf_to_text" }).json()
POST/api/pipeline/runRun Pipeline
Description

Run pipeline.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
globalbooleanSearch also across global pipelinesFalse
input *—
pinstringPIN. Omit if unspecified—
pipeline_name *stringPipeline name—
targetstringID (UUID) of the device on which the pipeline should run. Omit if unspecified—
waitbooleanWhether to wait for the task to complete before returning a responseTrue
Responses
CodeDescriptionResponse Schema
200Successful ResponseRunPipelineCompleteResult {execution_log, pipeline_name, result, run_time_ms, status} / RunPipelineDeferredResult {execution_log, pipeline_name, result, status, task_id}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status} / RunPipelineError {execution_log, message, pipeline_name, status}
Python example
Python
r = requests.post(f"{BASE}/api/pipeline/run", headers=H, json={ "pipeline_name": "my_pipeline", "input": null }).json()
POST/api/pipeline/saveSave Pipeline
Description

Save pipeline with description, blocks, connections and advanced settings.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
advanced_settingsobject—
api_keystringAPI key for embeddings and summarization—
blocksarray[]—
connectionsarray[Connection]—
description *stringPipeline description—
globalbooleanPipeline is globalFalse
name *stringPipeline name—
Responses
CodeDescriptionResponse Schema
200Successful ResponseSavePipelineResult {pipeline_name, status, user_id}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/pipeline/save", headers=H, json={ "name": "my_pipeline", "description": "description" }).json()
POST/api/pipeline/searchSearch Pipelines
Description

Semantic search for pipelines.

Headers: X-Auth-Token, X-Profile-Id, X-Agent-Id
Request Body application/json
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
globalbooleanSearch also across global pipelinesFalse
limitintegerResults limit10
query *stringSearch query—
Responses
CodeDescriptionResponse Schema
200Successful ResponseSearchPipelinesResult {matches, search_time_ms, status, total}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/pipeline/search", headers=H, json={ "query": "query" }).json()
✅ Tasks1 endpoint
POST/api/tasks/checkCheck Task
Description

Check task.

Request Body application/json
FieldTypeDescriptionDefault
task_id *string(uuid)—
Responses
CodeDescriptionResponse Schema
200Successful ResponseCheckTaskResult {result, status, task_id}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/tasks/check", headers=H, json={ "task_id": "uuid-of-target" }).json()
🗑️ Trash4 endpoints
POST/api/trash/clearClear Trash
Description

Clear trash.

Headers: X-Auth-Token
Responses
CodeDescriptionResponse Schema
200Successful ResponseClearTrashResponse {experts_deleted, pipelines_deleted, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/trash/clear", headers=H).json()
POST/api/trash/listList Trash
Description

List all experts and pipelines in trash.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
globalbooleanRetrieve also global trashed experts and pipelinesFalse
Responses
CodeDescriptionResponse Schema
200Successful ResponseListTrashResponse {experts, pipelines, retention_days, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/trash/list", headers=H).json()
POST/api/trash/restore/expertRestore Expert From Trash
Description

Restore expert from trash.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
name *stringExpert name—
Responses
CodeDescriptionResponse Schema
200Successful ResponseRestoreFromTrashResponse {restored, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/trash/restore/expert", headers=H, json={ "name": "pdf_to_text" }).json()
POST/api/trash/restore/pipelineRestore Pipeline From Trash
Description

Restore pipeline from trash.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
name *stringPipeline name—
Responses
CodeDescriptionResponse Schema
200Successful ResponseRestoreFromTrashResponse {restored, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/trash/restore/pipeline", headers=H, json={ "name": "my_pipeline" }).json()
🎫 Tokens4 endpoints
POST/api/token/createCreate Token
Description

Create new API token for user authentication.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
globalbooleanToken is globalFalse
namestringOptional friendly name for the token
Responses
CodeDescriptionResponse Schema
200Successful ResponseCreateTokenResult {name, status, token, user_id}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/token/create", headers=H).json()
POST/api/token/listList Tokens
Description

Get list of all tokens.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
globalbooleanRetrieve also global tokensFalse
Responses
CodeDescriptionResponse Schema
200Successful ResponseListTokensResult {count, status, tokens}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/token/list", headers=H).json()
POST/api/token/revokeRevoke Token
Description

Revoke (delete) token.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
token *stringToken string to revoke—
Responses
CodeDescriptionResponse Schema
200Successful ResponseRevokeTokenResult {revoked, status}
400Bad RequestBadRequestError {message, status}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/token/revoke", headers=H, json={ "token": "token" }).json()
POST/api/token/validateValidate Token
Description

Validate token and get associated user_id.

Request Body application/json
FieldTypeDescriptionDefault
token *stringToken string to validate—
Responses
CodeDescriptionResponse Schema
200Successful ResponseValidTokenResult {agent_id, name, profile_id, status, user_id, valid} / InvalidTokenResult {status, valid}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/token/validate", headers=H, json={ "token": "token" }).json()
🔒 PINs4 endpoints
POST/api/pin/deleteDelete Pin
Description

Delete PIN.

Headers: X-Auth-Token
Responses
CodeDescriptionResponse Schema
200Successful ResponseDeletePinResponse {message, status, user_id}
401UnauthorizedAuthenticationRequiredError {message, status}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/pin/delete", headers=H).json()
POST/api/pin/getGet Pin
Description

Get PIN.

Headers: X-Auth-Token
Responses
CodeDescriptionResponse Schema
200Successful ResponseGetPinResult {created_at, pin, status, updated_at, user_id}
401UnauthorizedAuthenticationRequiredError {message, status}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/pin/get", headers=H).json()
POST/api/pin/setSet Pin
Description

Set or update PIN.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
pin *string—
Responses
CodeDescriptionResponse Schema
200Successful ResponseSetPinResponse {message, pin_id, status, user_id}
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/pin/set", headers=H, json={ "pin": "pin" }).json()
POST/api/pin/verifyVerify Pin
Description

Verify PIN.

Headers: X-Auth-Token
Request Body application/json
FieldTypeDescriptionDefault
pin *string—
Responses
CodeDescriptionResponse Schema
200Successful ResponseResponse Verify Pin Api Pin Verify Post
401UnauthorizedAuthenticationRequiredError {message, status}
422Validation ErrorHTTPValidationError {detail}
500Internal Server ErrorError {message, status}
Python example
Python
r = requests.post(f"{BASE}/api/pin/verify", headers=H, json={ "pin": "pin" }).json()
Data Models

Schemas (Models)

148 data models from docx v1.2.3 — grouped by type. Required fields marked *.

📤 Request Bodies56 schemas
AddAgentToProfileRequestPOST /api/profile/add_agent
FieldTypeDescription
agent_id *stringID of the agent to add
profile_id *stringID of the profile to add the agent to
AddConceptRequestPOST /api/concept/add
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
globalbooleanConcept is globalFalse
text *stringConcept text (knowledge, pattern, or learning)—
AddRuleRequestPOST /api/rules/add
FieldTypeDescriptionDefault
globalbooleanRule is globalFalse
rule *stringRule text—
AddTargetRequestPOST /api/targets/add
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
description *stringHuman-readable description—
globalbooleanTarget is globalFalse
target *string(uuid)—
CheckTaskRequestPOST /api/tasks/check
FieldTypeDescription
task_id *string(uuid)
CreateAgentRequestPOST /api/agent/create
FieldTypeDescription
apiKeystringAPI key used to authenticate requests to the custom provider
baseURLstringBase URL for the custom provider API endpoint
categorystringAgent category
conversation_startersarray[string]Suggested conversation starters
descriptionstringAgent description
end_after_toolsbooleanEnd response generation after tool execution
hide_sequential_outputsbooleanHide intermediate sequential outputs
instructionsstringSystem instructions for the agent
model *stringModel name
model_parametersModelParametersModel/provider-specific parameters
namestringAgent name
provider *stringModel provider
recursion_limitintegerMaximum recursion depth
tool_optionsobjectPer-tool options
toolsarray[string]Enabled tool IDs
CreateProfileRequestPOST /api/profile/create
FieldTypeDescription
profile_name *stringProfile name
CreateTokenRequestPOST /api/token/create
FieldTypeDescriptionDefault
globalbooleanToken is globalFalse
namestringOptional friendly name for the token
DeleteAgentRequestPOST /api/agent/delete
FieldTypeDescription
agent_id *stringID of agent to delete
DeleteConceptRequestPOST /api/concept/delete
FieldTypeDescription
concept_id *integerID of concept to delete
DeleteExpertRequestPOST /api/expert/delete
FieldTypeDescription
name *stringExpert name
DeleteKeyRequestPOST /api/kv/delete
FieldTypeDescription
key *stringKey name to delete
DeletePipelineRequestPOST /api/pipeline/delete
FieldTypeDescription
name *stringPipeline name
DeleteProfileRequestPOST /api/profile/delete
FieldTypeDescription
profile_id *stringID of profile to delete
DeleteRuleRequestPOST /api/rules/delete
FieldTypeDescription
rule_id *stringID of rule to delete
DeleteTargetRequestPOST /api/targets/delete
FieldTypeDescription
id *string(uuid)
ExportCallsRequestPOST /api/agent/export/calls
FieldTypeDescription
by *string
fromstringOptional ISO-8601 lower bound (inclusive)
id *stringby agent: Agent ID; by profile: Profile ID
limitintegerOptional positive integer, default 200, max 1000
tostringOptional ISO-8601 upper bound (inclusive)
ExportChatsRequestPOST /api/agent/export/chats
FieldTypeDescription
by *string
id *stringby agent: Agent ID; by profile: Profile ID
GetAgentRequestPOST /api/agent/get
FieldTypeDescription
agent_id *stringAgent ID
GetExpertRequestPOST /api/experts_db/get
FieldTypeDescriptionDefault
globalbooleanSearch also across global expertsFalse
name *stringExpert name—
GetKeyRequestPOST /api/kv/get
FieldTypeDescriptionDefault
globalbooleanSearch also across global keysFalse
key *stringExact key name to retrieve—
GetPipelineRequestPOST /api/pipeline/get
FieldTypeDescriptionDefault
globalbooleanSearch also across global pipelinesFalse
name *stringPipeline name—
ListAgentsRequestPOST /api/agent/list
FieldTypeDescription
profile_idstringProfile ID to filter agents by. If omitted, all agents are returned
ListConceptsRequestPOST /api/concept/list
FieldTypeDescriptionDefault
globalbooleanRetrieve also global conceptsFalse
limitintegerMax results—
offsetintegerPagination offset0
ListExpertsRequestPOST /api/expert/list
FieldTypeDescriptionDefault
globalbooleanRetrieve also global expertsFalse
limitintegerMax results—
offsetintegerPagination offset0
ListKeysRequestPOST /api/kv/list
FieldTypeDescriptionDefault
globalbooleanRetrieve also global key-value pairsFalse
ListPipelinesRequestPOST /api/pipeline/list
FieldTypeDescriptionDefault
globalbooleanRetrieve also global pipelinesFalse
limitintegerMax results—
offsetintegerPagination offset0
ListRulesRequestPOST /api/rules/list
FieldTypeDescriptionDefault
globalbooleanRetrieve also global rulesFalse
ListTargetsRequestPOST /api/targets/list
FieldTypeDescriptionDefault
globalbooleanRetrieve also global targetsFalse
ListTokensRequestPOST /api/token/list
FieldTypeDescriptionDefault
globalbooleanRetrieve also global tokensFalse
ListTrashRequestPOST /api/trash/list
FieldTypeDescriptionDefault
globalbooleanRetrieve also global trashed experts and pipelinesFalse
RemoveExpertRequestPOST /api/expert/remove
FieldTypeDescription
name *stringExpert name
RemovePipelineRequestPOST /api/pipeline/remove
FieldTypeDescription
name *stringExpert name
RestoreExpertFromTrashRequestPOST /api/trash/restore/expert
FieldTypeDescription
name *stringExpert name
RestorePipelineFromTrashRequestPOST /api/trash/restore/pipeline
FieldTypeDescription
name *stringPipeline name
RevokeTokenRequestPOST /api/token/revoke
FieldTypeDescription
token *stringToken string to revoke
RunAgentRequestPOST /api/agent/run
FieldTypeDescriptionDefault
agent_id *stringID of agent to run—
input *array | stringEither a plain user message string or a list of OpenResponses input items—
instructionsstring—
max_output_tokensintegerMaximum number of tokens to generate—
previous_response_idstringID of a previous response to continue from—
run_timeoutnumberAgent run timeout (in seconds)120
storebooleanWhether to persist the conversation (false disables saving to /export/chats and /export/calls)True
temperaturenumberSampling temperature—
tool_choiceobject | stringTool selection strategy (auto, none, or specific tool config)—
toolsarray[Tool]List of tools available to the agent—
RunExpertRequestPOST /api/expert/run
FieldTypeDescriptionDefault
expert_name *stringExpert name—
globalbooleanSearch also across global expertsFalse
isolatedbooleanIsolated run in virtual environmentFalse
paramsobjectExpert parameters—
pinstringPIN. Omit if unspecified—
targetstringID (UUID) of the device on which the expert should run. Omit if unspecified—
waitbooleanWhether to wait for the task to complete before returning a responseTrue
RunPipelineRequestPOST /api/pipeline/run
FieldTypeDescriptionDefault
globalbooleanSearch also across global pipelinesFalse
input *—
pinstringPIN. Omit if unspecified—
pipeline_name *stringPipeline name—
targetstringID (UUID) of the device on which the pipeline should run. Omit if unspecified—
waitbooleanWhether to wait for the task to complete before returning a responseTrue
SaveExpertRequestPOST /api/expert/save
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
code *stringExpert code—
csplstringCSPL code typefython
description *stringExpert description (in English!)—
globalbooleanExpert is globalFalse
kwargsobjectExpert parameters with defaults—
name *stringUnique expert name (snake_case)—
SavePipelineRequestPOST /api/pipeline/save
FieldTypeDescriptionDefault
advanced_settingsobject—
api_keystringAPI key for embeddings and summarization—
blocksarray[]—
connectionsarray[Connection]—
description *stringPipeline description—
globalbooleanPipeline is globalFalse
name *stringPipeline name—
SearchConceptRequestPOST /api/concept/search
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
globalbooleanSearch also across global conceptsFalse
limitintegerMaximum number of results5
query *stringSearch query text—
SearchExpertsRequestPOST /api/expert/search
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
globalbooleanSearch also global expertsFalse
limitintegerResults limit10
query *stringSearch query—
SearchKeyRequestPOST /api/kv/search
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
globalbooleanSearch also across global keysFalse
limitintegerMaximum results5
query *stringSearch query—
SearchPipelinesRequestPOST /api/pipeline/search
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
globalbooleanSearch also across global pipelinesFalse
limitintegerResults limit10
query *stringSearch query—
SearchTargetsRequestPOST /api/targets/search
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
globalbooleanSearch also across global targetsFalse
limitintegerMaximum results5
query *string—
SetDefaultTargetRequestPOST /api/defaults/set_target
FieldTypeDescription
target *string(uuid)
SetKeyRequestPOST /api/kv/set
FieldTypeDescriptionDefault
api_keystringAPI key for embeddings—
descriptionstringOptional description for semantic search
globalbooleanKey-value pair is globalFalse
key *stringUnique key name—
value *stringValue to store—
SetPinRequestPOST /api/pin/set
FieldTypeDescription
pin *string
UpdateAgentRequestPOST /api/agent/update
FieldTypeDescription
agent_id *stringID of agent to update
apiKeystringAPI key used to authenticate requests to the custom provider
baseURLstringBase URL for the custom provider API endpoint
categorystringAgent category
conversation_startersarray[string]Suggested conversation starters
descriptionstringAgent description
end_after_toolsbooleanEnd response generation after tool execution
hide_sequential_outputsbooleanHide intermediate sequential outputs
instructionsstringSystem instructions for the agent
modelstringModel name
model_parametersModelParametersModel/provider-specific parameters
namestringAgent name
providerstringModel provider
recursion_limitintegerMaximum recursion depth
tool_optionsobjectPer-tool options
toolsarray[string]Enabled tool IDs
UpdateConceptRequestPOST /api/concept/update
FieldTypeDescription
api_keystringAPI key for embeddings
concept_id *integerID of concept to update
new_text *stringNew text content
UpdateRuleRequestPOST /api/rules/update
FieldTypeDescription
rule *stringRule text
rule_id *stringID of rule to update
UpdateTargetRequestPOST /api/targets/update
FieldTypeDescription
api_keystringAPI key for embeddings
descriptionstring
id *string
targetstring
UpsertExpertRequestPOST /api/experts_db/upsert
FieldTypeDescription
api_keystringAPI key for embeddings
description *stringExpert description
name *stringExpert name
ValidateTokenRequestPOST /api/token/validate
FieldTypeDescription
token *stringToken string to validate
VerifyPinRequestPOST /api/pin/verify
FieldTypeDescription
pin *string
📥 Response Bodies50 schemas
AddConceptResult200 /api/concept/add
FieldTypeDescriptionDefault
id *integer—
statusstringsuccess
text *string—
AddRuleResult200 /api/rules/add
FieldTypeDescriptionDefault
rule *stringRule text—
rule_id *stringID of added rule—
statusstringsuccess
AddTargetResult200 /api/targets/add
FieldTypeDescriptionDefault
description *stringTarget description—
id *string(uuid)—
statusstringsuccess
target *string—
CheckTaskResult200 /api/tasks/check
FieldTypeDescription
result *stringstatus = `completed`: task result; status = `error`: error message
status *stringTask status
task_id *string(uuid)
ClearTrashResponse200 /api/trash/clear
FieldTypeDescriptionDefault
experts_deleted *integer—
pipelines_deleted *integer—
statusstringsuccess
CreateTokenResult200 /api/token/create
FieldTypeDescriptionDefault
name *stringFriendly name for the token—
statusstringsuccess
token *stringGenerated token string—
user_id *string—
DeleteExpertResult200 /api/expert/delete
FieldTypeDescriptionDefault
message *string—
statusstringsuccess
DeletePinResponse200 /api/pin/delete
FieldTypeDescriptionDefault
messagestringPIN deleted successfully
statusstringsuccess
user_id *string—
DeletePipelineResult200 /api/pipeline/delete
FieldTypeDescriptionDefault
message *string—
statusstringsuccess
DeleteResult200 /api/concept/delete
FieldTypeDescriptionDefault
deleted *boolean—
statusstringsuccess
GetCurrentAgentResponse200 /api/agent/get_current
FieldTypeDescription
agent_id *string
profile_id *string
GetDefaultTargetResponse200 /api/defaults/get_target
FieldTypeDescriptionDefault
statusstringsuccess
target *string—
GetExpertDescriptionResult200 /api/experts_db/get
FieldTypeDescriptionDefault
description *stringExpert description—
globalbooleanExpert is globalFalse
group_name *stringGroup name—
id *integer—
name *stringExpert name—
statusstringsuccess
GetExpertResult200 /api/expert/get
FieldTypeDescriptionDefault
createdAt *string(date-time)—
cspl *stringCSPL code type—
expert_code *stringExpert code—
expert_description *stringExpert description—
expert_name *stringExpert name—
expert_params *objectExpert parameters with defaults—
globalbooleanExpert is globalFalse
group_name *stringGroup name—
statusstringsuccess
updatedAt *string(date-time)—
GetKeyResult200 /api/kv/get
FieldTypeDescriptionDefault
created_at *string(date-time)—
description *stringDescription for semantic search—
globalbooleanKey is globalFalse
id *integer—
key *stringKey name—
statusstringsuccess
updated_at *string(date-time)—
value *stringValue—
GetPinResult200 /api/pin/get
FieldTypeDescriptionDefault
created_at *string(date-time)—
pin *string—
statusstringsuccess
updated_at *string(date-time)—
user_id *string—
GetPipelineFullResult200 /api/pipeline/get
FieldTypeDescriptionDefault
advanced_settings *object—
blocks *array[Block]—
connections *array[Connection]—
created_at *string(date-time)—
description *string—
globalbooleanPipeline is globalFalse
id *integer—
name *string—
statusstringsuccess
updated_at *string(date-time)—
HealthResponse200 /api/health
FieldTypeDescriptionDefault
experts_db_available *boolean—
statusstringhealthy
InvalidTokenResult200 /api/token/validate
FieldTypeDescriptionDefault
statusstringsuccess
validbooleanFalse
ListConceptsResult200 /api/concept/list
FieldTypeDescriptionDefault
count *integer—
results *array[ListConceptResult]—
statusstringsuccess
ListExpertsResult200 /api/expert/list
FieldTypeDescriptionDefault
count *integer—
results *array[ListExpertResult]—
statusstringsuccess
ListKeysResult200 /api/kv/list
FieldTypeDescriptionDefault
count *integer—
results *array[ListKeyResult]—
statusstringsuccess
ListPipelinesResult200 /api/pipeline/list
FieldTypeDescriptionDefault
count *integer—
results *array[ListPipelineResult]—
statusstringsuccess
ListRulesResult200 /api/rules/list
FieldTypeDescriptionDefault
count *integer—
results *array[ListRuleResult]—
statusstringsuccess
ListTargetsResult200 /api/targets/list
FieldTypeDescriptionDefault
count *integer—
results *array[ListTargetResult]—
statusstringsuccess
ListTokensResult200 /api/token/list
FieldTypeDescriptionDefault
count *integer—
statusstringsuccess
tokens *array[ListTokenResult]—
ListTrashResponse200 /api/trash/list
FieldTypeDescriptionDefault
experts *array[ListExpertResult]—
pipelines *array[ListPipelineResult]—
retention_days *integer—
statusstringsuccess
RemoveResult200 /api/expert/remove
FieldTypeDescriptionDefault
removed *boolean—
statusstringsuccess
RestoreFromTrashResponse200 /api/trash/restore/expert
FieldTypeDescriptionDefault
restored *boolean—
statusstringsuccess
RevokeTokenResult200 /api/token/revoke
FieldTypeDescriptionDefault
revoked *boolean—
statusstringsuccess
RunExpertCompleteResult200 /api/expert/run
FieldTypeDescriptionDefault
execution_log *array[string]Log messages generated during expert execution—
expert_name *stringExpert name—
result *string—
run_time_ms *integerExpert runtime in milliseconds—
statusstringsuccess
RunExpertDeferredResult200 /api/expert/run
FieldTypeDescriptionDefault
execution_log *array[string]Log messages generated during expert execution—
expert_name *stringExpert name—
result *string—
statusstringsuccess
task_id *string(uuid)ID of the deferred expert execution task—
RunPipelineCompleteResult200 /api/pipeline/run
FieldTypeDescriptionDefault
execution_log *array[string]Log messages generated during pipeline execution—
pipeline_name *stringPipeline name—
result *—
run_time_ms *integerPipeline runtime in milliseconds—
statusstringsuccess
RunPipelineDeferredResult200 /api/pipeline/run
FieldTypeDescriptionDefault
execution_log *array[string]Log messages generated during pipeline execution—
pipeline_name *stringPipeline name—
result *—
statusstringsuccess
task_id *string(uuid)ID of the deferred pipeline execution task—
SaveExpertResult200 /api/expert/save
FieldTypeDescriptionDefault
expert_name *stringExpert name—
statusstringsuccess
SavePipelineResult200 /api/pipeline/save
FieldTypeDescriptionDefault
pipeline_name *stringPipeline name—
statusstringsuccess
user_id *string—
SearchConceptsResult200 /api/concept/search
FieldTypeDescriptionDefault
count *integer—
results *array[SearchConceptResult]—
statusstringsuccess
SearchExpertsResult200 /api/expert/search
FieldTypeDescriptionDefault
count *integer—
experts *array[SearchExpertResult]—
statusstringsuccess
SearchKeysResult200 /api/kv/search
FieldTypeDescriptionDefault
count *integer—
results *array[SearchKeyResult]—
statusstringsuccess
SearchPipelinesResult200 /api/pipeline/search
FieldTypeDescriptionDefault
matches *array[SearchPipelineMatch]—
search_time_ms *number—
statusstringsuccess
total *integer—
SearchTargetsResult200 /api/targets/search
FieldTypeDescriptionDefault
count *integer—
results *array[SearchTargetResult]—
statusstringsuccess
SetDefaultTargetResponse200 /api/defaults/set_target
FieldTypeDescriptionDefault
statusstringsuccess
target *string(uuid)—
SetKeyResult200 /api/kv/set
FieldTypeDescriptionDefault
description *stringStored description for semantic search—
id *integer—
key *stringKey name—
statusstringsuccess
value *stringStored value—
SetPinResponse200 /api/pin/set
FieldTypeDescriptionDefault
messagestringPIN set successfully
pin_id *integer—
statusstringsuccess
user_id *string—
UpdateConceptResult200 /api/concept/update
FieldTypeDescriptionDefault
id *integerID of updated concept—
statusstringsuccess
text *stringNew text content—
UpdateRuleResult200 /api/rules/update
FieldTypeDescriptionDefault
rule *stringRule text—
rule_id *stringID of updated rule—
statusstringsuccess
UpdateTargetResult200 /api/targets/update
FieldTypeDescriptionDefault
description *stringTarget description—
id *string(uuid)—
statusstringsuccess
target *string—
UpsertExpertResult200 /api/experts_db/upsert
FieldTypeDescriptionDefault
description *stringExpert description—
id *integer—
name *stringExpert name—
statusstringsuccess
ValidTokenResult200 /api/token/validate
FieldTypeDescriptionDefault
agent_id *string—
name *stringFriendly name for the token—
profile_id *string—
statusstringsuccess
user_id *string—
validbooleanTrue
⚠️ Error Schemas6 schemas
AuthenticationRequiredError401 responses
FieldTypeDescription
messagestring
statusstring
BadRequestError400 responses
FieldTypeDescription
message *stringError message
statusstring
Error500 responses
FieldTypeDescription
message *stringError message
statusstring
HTTPValidationError422 responses
FieldTypeDescription
detailarray[ValidationError]
🔁 Sub-models20 schemas
BlockInside GetPipelineFullResult.blocks
FieldTypeDescription
blockType *string
id *string(uuid)
isInitialBlock *boolean
positionPosition
text *stringblock name
ConnectionInside GetPipelineFullResult.connections
FieldTypeDescription
endID *string(uuid)
id *string(uuid)
sourceHandleSourceHandle
startID *string(uuid)
targetHandleTargetHandle
ListConceptResultInside ListConceptsResult.results
FieldTypeDescription
concept_id *integerID of concept
concept_text *stringConcept text
created_at *string(date-time)
globalbooleanConcept is global
group_name *stringGroup name
updated_at *string(date-time)
ListExpertResultInside ListExpertsResult.results
FieldTypeDescription
created_at *string(date-time)
deleted_atstring(date-time)
description *stringExpert description
globalbooleanExpert is global
group_name *stringGroup name
id *integer
name *stringExpert name
updated_at *string(date-time)
ListKeyResultInside ListKeysResult.results
FieldTypeDescription
created_at *string(date-time)
globalbooleanKey is global
kv_description *stringDescription for semantic search
kv_id *integer
kv_key *stringKey name
kv_value *stringValue
updated_at *string(date-time)
ListPipelineResultInside ListPipelinesResult.results
FieldTypeDescription
created_at *string(date-time)
deleted_atstring(date-time)
description *stringPipeline description
globalbooleanPipeline is global
id *integer
name *stringPipeline name
updated_at *string(date-time)
ListRuleResultInside ListRulesResult.results
FieldTypeDescription
created_at *string(date-time)
globalbooleanRule is global
group_name *stringGroup name
id *string
rule *stringRule text
updated_at *string(date-time)
ListTargetResultInside ListTargetsResult.results
FieldTypeDescription
created_at *string(date-time)
description *stringTarget description
globalbooleanTarget is global
id *string(uuid)
target *string
updated_at *string(date-time)
ListTokenResultInside ListTokensResult.tokens
FieldTypeDescription
created_at *string(date-time)
name *stringFriendly name for the token
revoked *boolean
token *stringToken string
ModelParametersInside CreateAgentRequest.model_parameters
FieldTypeDescription
disableStreamingbooleanopenAI, azureOpenAI, custom (OpenAI-like): Disables streaming responses from the model
effortstringanthropic, bedrock (Anthropic models): Controls the Adaptive Thinking effort level for supported Anthropic models (e.g., Claude Opus 4.6+). Higher effort levels allocate more thinking tokens for complex problems
fileTokenLimitintegerSet maximum token limit for file processing to control costs and resource usage
frequency_penaltynumberopenAI, azureOpenAI, custom (OpenAI-like): Penalty for repeated tokens, reducing redundancy in responses
imageDetailstringThe resolution for Vision requests. `low` is cheaper and faster, `high` is more detailed and expensive, and `auto` will automatically choose between the two based on the image resolution
maxContextTokensintegerThe maximum number of context tokens to provide to the model
maxOutputTokensintegergoogle, anthropic: The maximum number of tokens in the response
maxTokensintegerbedrock: Maximum output tokens for Amazon Bedrock endpoints
max_tokensintegeropenAI, azureOpenAI, custom (OpenAI-like): The maximum number of tokens in the model response
presence_penaltynumberopenAI, azureOpenAI, custom (OpenAI-like): Penalty for repetitive tokens, encouraging exploration of new topics
promptCachebooleananthropic, bedrock (Anthropic and Nova models): Enables or disables built-in prompt caching
reasoning_effortstringopenAI, azureOpenAI, custom (OpenAI-like), bedrock (ZAI, MoonshotAI models): Controls the reasoning effort level for the model. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning. The `xhigh` option provides maximum reasoning capability for complex problems. For Bedrock, accepted values are `low`, `medium`, `high`
reasoning_summarystringopenAI, azureOpenAI, custom (OpenAI-like): Sets reasoning summary preferences for the model
regionstringbedrock: AWS region for Amazon Bedrock endpoints
resendFilesbooleanResend all previously attached files. Note: this will increase token cost and you may experience errors with many attachments
stoparray[string]openAI, azureOpenAI, custom (OpenAI-like): Stop tokens for the model, instructing it to end its response if encountered
temperaturenumberopenAI, azureOpenAI, custom (OpenAI-like), google, anthropic, bedrock: Controls how deterministic or “creative” the model responses are
thinkingbooleangoogle, anthropic, bedrock (Anthropic models): Indicates whether the model should spend time thinking before generating a response
thinkingBudgetinteger | stringgoogle, anthropic, bedrock (Anthropic models): Controls the number of thinking tokens the model can use for internal reasoning. Larger budgets can improve response quality for complex problems
thinkingDisplaystringanthropic, bedrock (Anthropic models): Controls whether reasoning content is returned in model responses. Claude Opus 4.7+ omits thinking content by default; this setting lets you opt in to reasoning summaries or explicitly suppress them
thinkingLevelstringgoogle (Gemini 3+ models): Controls the thinking effort level for Gemini 3+ models. Gemini 2.5 models use `thinkingBudget` instead
topKintegergoogle, anthropic: Limits the next token selection to the top K tokens
topPnumbergoogle, anthropic: Nucleus sampling parameter
top_pnumberopenAI, azureOpenAI, custom (OpenAI-like): Nucleus sampling parameter (0-1), controlling the randomness of tokens
useResponsesApibooleanopenAI, azureOpenAI, custom (OpenAI-like): Enables or disables the responses API for the model
verbositystringopenAI, azureOpenAI, custom (OpenAI-like): Controls the verbosity level of model responses
web_searchbooleanopenAI, azureOpenAI, custom (OpenAI-like), google, anthropic: Enables or disables web search functionality for the model
PositionInside Block.position
FieldTypeDescription
x *number
y *number
SearchConceptResultInside SearchConceptsResult.results
FieldTypeDescription
concept_id *integerID of concept
concept_text *stringConcept text
created_at *string(date-time)
globalbooleanConcept is global
group_name *stringGroup name
similarity *numberSemantic similarity score between the query and the concept (0.0 to 1.0)
SearchExpertResultInside SearchExpertsResult.experts
FieldTypeDescription
code *stringExpert code
description *stringExpert description
globalbooleanExpert is global
group_name *stringGroup name
id *integer
kwargs *objectExpert parameters with defaults
name *stringExpert name
similarity *numberSemantic similarity score between the query and the name+description (0.0 to 1.0)
SearchKeyResultInside SearchKeysResult.results
FieldTypeDescription
created_at *string(date-time)
globalbooleanKey is global
kv_description *stringDescription for semantic search
kv_id *integer
kv_key *stringKey name
kv_value *stringValue
similarity *numberSemantic similarity score between the query and the key+value+description (0.0 to 1.0)
updated_at *string(date-time)
SearchPipelineMatchInside SearchPipelinesResult.matches
FieldTypeDescription
advanced_settings *object
blocks *array[Block]
connections *array[Connection]
description *stringPipeline description
globalbooleanPipeline is global
name *stringPipeline name
score *integerPercentage of match
SearchTargetResultInside SearchTargetsResult.results
FieldTypeDescription
description *stringTarget description
globalbooleanTarget is global
id *string(uuid)
similarity *numberSemantic similarity score between the query and the tagret+description (0.0 to 1.0)
target *string
SourceHandleInside Connection.sourceHandle
FieldTypeDescription
No properties
TargetHandleInside Connection.targetHandle
FieldTypeDescription
No properties
ToolInside RunAgentRequest.tools
FieldTypeDescription
description *string
name *string
parametersToolParameters
type *string
ToolParametersInside Tool.parameters
FieldTypeDescription
propertiesobject
requiredarray[string]
type *string
👥 Shared / Utility18 schemas
EditableGet output from editableText
FieldTypeDescription
blockTypestring
editableText *string
id *string(uuid)
isInitialBlock *boolean
positionPosition
text *stringblock name
ExpertSelector
FieldTypeDescription
blockTypestring
editableText *string
id *string(uuid)
isInitialBlock *boolean
paramsobject
positionPosition
text *stringblock name
GenericContentPart
FieldTypeDescription
type *string
GenericItem
FieldTypeDescription
type *string
InputterGet output from last executed input
FieldTypeDescription
blockTypestring
id *string(uuid)
isInitialBlock *boolean
positionPosition
text *stringblock name
MessageItem
FieldTypeDescription
content *array | string
role *string
type *string
PipelinePipeline block
FieldTypeDescription
blockTypestring
id *string(uuid)
isInitialBlock *boolean
paramInputMappingobject
paramModeobject
paramsobject
positionPosition
text *stringblock name
RunExpertError
FieldTypeDescription
execution_log *array[string]Log messages generated during expert execution
expert_name *stringExpert name
message *stringError message
statusstring
RunPipelineError
FieldTypeDescription
execution_log *array[string]Log messages generated during pipeline execution
message *stringError message
pipeline_name *stringPipeline name
statusstring
SearchBlockResult
FieldTypeDescription
code *stringExpert code
description *stringExpert description
globalbooleanExpert is global
kwargs *objectExpert parameters with defaults
name *stringExpert name
score *integerPercentage of match
SearchBlocksRequest
FieldTypeDescription
api_keystringAPI key for embeddings
globalbooleanSearch also across global experts
limitintegerResults limit
querystringSearch query
SearchBlocksResult
FieldTypeDescription
matches *array[SearchBlockResult]
search_time_ms *numberSearch time in milliseconds
statusstring
total *integer
StandardExpert
FieldTypeDescription
blockTypestring
id *string(uuid)
isInitialBlock *boolean
paramInputMappingobject
paramModeobject
paramsobject
positionPosition
text *stringblock name
Switch
FieldTypeDescription
blockTypestring
id *string(uuid)
isInitialBlock *boolean
paramInputMappingobject
paramModeobject
paramsobject
positionPosition
text *stringblock name
ToolOptionsSchemaPer-tool options schema
FieldTypeDescription
allowed_callersarray[string]Allowed caller types
defer_loadingbooleanDefer tool loading until first use
ToolProperty
FieldTypeDescription
descriptionstring
type *string
VerifyPinFoundResult
FieldTypeDescription
statusstring
user_id *string
validboolean
VerifyPinNotFoundResult
FieldTypeDescription
messagestring
statusstring
validboolean
Developer Experience

Everything you need to ship fast.

Persistent AI agents embedded in your product without friction.

🔑
Bearer Token Auth
One token per user. Validate once, use everywhere. Agent and profile IDs always in headers — never in the body.
⚡
SSE Streaming
Real-time responses via Server-Sent Events. Set "stream": true and receive token-by-token output as it generates.
🧠
Persistent Agents
Every agent retains concepts, KV memory and rules between calls. Conversations compound. Context never resets.
👥
Teams via Profiles
Group up to 5 agents into a profile with shared knowledge base. Export combined history in one request.
📊
Export & Analytics
Full audit trail — every token count, latency, model and HTTP code. Filter by date range.
🛡
Rate Limits
60 req/min per IP. 120 per user. 20 runs/min for /agent/run. Clean 429 with retry_after_seconds.

Ready to build?

Open the full reference and start integrating in minutes.

View API Docs →
Download for macOS Windows