Execute Agent

Execute a research agent. The request blocks until the agent finishes execution (synchronous).

Client timeout caveat. This endpoint holds the HTTP connection until executeAgentRun completes all of LLM inference, tool invocations (browsing/search), RAG, and graph extraction. Typical runs take 10 seconds to several minutes depending on the task.If the client times out (default 30–120s in most HTTP libraries), the connection is dropped — but the server keeps running and the result is persisted to chat history, not returned to the caller. You can recover it later via GET /turn/list.Recommendation: use Execute Agent (Streaming) for anything beyond trivial Q&A. SSE returns the runId immediately in the first event and can be resumed with /agent/run/stream/{runId} if the connection drops. If you must use this non-streaming endpoint, set your client timeout to at least 300 seconds.

Request

POST /api/v1/agent/run

Headers

Header	Required	Description
`Authorization`	Yes	API key in `Bearer snorbe_...` format
`Content-Type`	Yes	`application/json`

Request Body

{
  "modelName": "gpt-5-mini-2025-08-07",
  "inputText": "Research the latest semiconductor trends",
  "promptKey": "chat-routing",
  "locale": "en",
  "fileUrls": []
}

Parameters

Parameter	Type	Required	Description
`modelName`	`string`	Yes	Model name
`inputText`	`string`	Yes	Input text for the agent
`promptKey`	`string`	Yes	Prompt key (typically `"chat-routing"`)
`locale`	`string`	Yes	`"ja"` or `"en"`
`fileUrls`	`string[]`	No	Attached file URLs (max 10). Default: `[]`
`agentId`	`string`	No	Agent ID. Defaults to the default agent
`mentions`	`Mention[]`	No	@mention references (entities, agent runs, sources, other Agents). Default: `[]`. Including `type: "agent"` lets the target Agent delegate via `mentionAgent`. See “Agent-to-Agent delegation” below
`maxBrowsingSteps`	`number`	No	Max browsing steps (1-100)
`maxChainSteps`	`number`	No	Maximum depth of Agent-to-Agent mention chains (1-50, default 10). Recursive `mentionAgent` fan-outs are capped at this value
`maxRetries`	`number`	No	Retry count (0-5)
`retryDelayMs`	`number`	No	Retry delay in ms (0-10000)
`includeOthersEntities`	`boolean`	No	Include other users’ entities in RAG search. Default: `true`
`extendedContextEnabled`	`boolean`	No	Extended context (uses 80% of model max tokens). Default: `false`
`matrixEditContext`	`object`	No	Matrix edit context (`sourceRunId` + `selection`)
`matrixContinueContext`	`object`	No	Matrix continue context (`sourceRunId`)
`matrixSelectionContent`	`string`	No	Matrix selection XML (`<matrix_selection>` format)

workspaceId is not required. It is automatically resolved from the API key.

Response

{
  "text": "Research results...",
  "finishReason": "stop",
  "model": {
    "id": "gpt-5-mini-2025-08-07",
    "provider": "openai"
  },
  "runId": "clxyz...",
  "status": "completed",
  "assistantTurnId": "clxyz...",
  "agentId": "clxyz...",
  "agentName": "agent"
}

Response Fields

Field	Type	Description
`text`	`string`	Agent response text
`finishReason`	`string`	Finish reason (`"stop"`, `"tool-calls"`, etc.)
`model`	`object`	Model information used
`runId`	`string`	Agent run ID
`status`	`string`	Execution status (`"completed"`, `"error"`, etc.)

Examples

curl -X POST "https://app.snorbe.deskrex.ai/api/v1/agent/run" \
  -H "Authorization: Bearer snorbe_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "modelName": "gpt-5-mini-2025-08-07",
    "inputText": "Research the latest semiconductor trends",
    "promptKey": "chat-routing",
    "locale": "en"
  }'

import requests

# Set a generous timeout — agent runs with tools/RAG/graph extraction
# regularly take several minutes. If you hit the client timeout, the server
# still finishes; recover the result via GET /turn/list.
resp = requests.post(
    "https://app.snorbe.deskrex.ai/api/v1/agent/run",
    headers={
        "Authorization": "Bearer snorbe_your_api_key_here",
        "Content-Type": "application/json",
    },
    json={
        "modelName": "gpt-5-mini-2025-08-07",
        "inputText": "Research the latest semiconductor trends",
        "promptKey": "chat-routing",
        "locale": "en",
    },
    timeout=600,
)
data = resp.json()
print(data["text"])
print(f"Run ID: {data['runId']}")

const resp = await fetch("https://app.snorbe.deskrex.ai/api/v1/agent/run", {
  method: "POST",
  headers: {
    Authorization: "Bearer snorbe_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    modelName: "gpt-5-mini-2025-08-07",
    inputText: "Research the latest semiconductor trends",
    promptKey: "chat-routing",
    locale: "en",
  }),
});
const data = await resp.json();
console.log(data.text);
console.log(`Run ID: ${data.runId}`);

Retrieving detailed run data after completion

GET /agent/run/{runId}/status is lightweight — it returns only status and pending*Draft flags. To recover full run details (browse steps, tool calls, plan and report and matrix drafts, graph extraction events, referenced sources), use GET /turn/list. Each turn entry includes:

agentRun.process — the persisted timeline of every SSE event emitted during the run (config, delta, step, browse-*, plan-*, report-structure-*, matrix-*, source-summary-*, graph-*)
agentRun.publicSourceAgentRuns / privateSourceAgentRuns — URL sources the agent referenced, including bodyLinks metadata
agentRun.agent — agent metadata

There is no direct GET /agent/run/{runId} endpoint. To find a specific runId, paginate /turn/list (newest first) and match turns[].agentRun.id.

Agent-to-Agent delegation

Including type: "agent" entries in mentions lets the target Agent delegate to mentioned peers mid-run.

Single target

{
  "inputText": "Ask [agent-beta](agent://b-id) for their favorite color in one word",
  "mentions": [
    { "id": "b-id", "type": "agent", "label": "agent-beta" }
  ]
}

What happens:

The initial Agent (e.g. agent-alpha) starts its run
Its LLM selects the mentionAgent tool and writes a final message like [@agent-beta](agent://b-id) favorite color in one word
After alpha completes, the server automatically starts a new AgentRun for agent-beta, using alpha’s final message as input
beta runs independently and its reply is persisted to chat history

The response runId is for the parent run (alpha) only. To retrieve child runs, use /turn/list or /agent/run/{childRunId}/status.

Multiple targets

When two or more agents are mentioned, a server-side LLM classifier decides parallel vs chain from the message intent.

parallel (independent opinions): all mentioned agents run concurrently. Example: “Ask A and B for their independent opinions”
chain (sequential): the primary agent runs first and chains to the others via mentionAgent. Example: “A drafts a plan, then B reviews it”

Guards

Self-loop prevention: targets that match the caller’s own agentId are skipped
Depth limit: maxChainSteps (1-50, default 10) caps recursive mentionAgent fan-outs
Error isolation: one child’s failure does not block other siblings from spawning

Error Responses

HTTP Status	Code	Description
400	`BAD_REQUEST`	Validation error
401	`UNAUTHORIZED`	Invalid API key
429	`TOO_MANY_REQUESTS`	Rate limit exceeded
500	`INTERNAL_SERVER_ERROR`	Agent execution error

​Execute Agent

​Request

​Headers

​Request Body

​Parameters

​Response

​Response Fields

​Examples

​Retrieving detailed run data after completion

​Agent-to-Agent delegation

​Single target

​Multiple targets

​Guards

​Error Responses

Execute Agent

Request

Headers

Request Body

Parameters

Response

Response Fields

Examples

Retrieving detailed run data after completion

Agent-to-Agent delegation

Single target

Multiple targets

Guards

Error Responses