> ## Documentation Index > Fetch the complete documentation index at: https://docs.sidenet.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run agent > Runs the agent's active published version against `messages`. Send `agentVersionId` to run a specific version (a draft, or an older published one) instead. Returns the finished turn as JSON: `text` is the answer, `toolCalls` what the agent called on the way, `data` the custom parts. This is the same run POST /v1/chat performs — same routing, memory, tools, usage accounting and cost — with the stream collected server-side, so it responds only when the turn is complete and takes as long as the turn takes. Use /v1/chat when you want tokens as they are generated. Pass the returned `threadId` back to continue the conversation. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/agents/{id}/run openapi: 3.1.0 info: title: Sidenet API version: 1.0.0 description: >- Sidenet HTTP endpoints exposed by the Sidenet Studio. All routes require an api key that can be generated through the studio in studio.sidenet.ai. servers: - url: https://api.sidenet.ai security: - bearerAuth: [] paths: /v1/agents/{id}/run: post: tags: - Chat summary: Run agent description: >- Runs the agent's active published version against `messages`. Send `agentVersionId` to run a specific version (a draft, or an older published one) instead. Returns the finished turn as JSON: `text` is the answer, `toolCalls` what the agent called on the way, `data` the custom parts. This is the same run POST /v1/chat performs — same routing, memory, tools, usage accounting and cost — with the stream collected server-side, so it responds only when the turn is complete and takes as long as the turn takes. Use /v1/chat when you want tokens as they are generated. Pass the returned `threadId` back to continue the conversation. parameters: - name: id in: path required: true schema: type: string example: 6f1c0f4e-2b7a-4a51-9a2f-0c9d1b3e5a10 description: Agent id. requestBody: required: true content: application/json: schema: type: object properties: messages: type: array default: [] description: >- The conversation, in AI SDK UIMessage format: `[{ "role": "user", "parts": [{ "type": "text", "text": "..." }] }]`. Send the whole exchange you want the agent to see; with a `threadId` the stored history is loaded too, so the new turn is usually the only entry. May be empty only on an `approval` continuation. example: - role: user parts: - type: text text: Where is my order? approval: type: object properties: runId: type: string minLength: 1 description: runId from the data-tool-call-approval chunk toolCallId: type: string minLength: 1 description: >- Disambiguates when multiple tool calls are pending; defaults to the most recent approved: type: boolean description: true = run the tool, false = decline it required: - runId - approved additionalProperties: false description: >- Approve or decline a tool call that paused the previous stream example: runId: run_6d20a95c toolCallId: call_a17f3b approved: true agentVersionId: type: string description: >- Optional override: run a specific agent version (e.g. preview a draft or an earlier published version) instead of the active one example: b3f7a2c8-5d19-4e6b-8f02-1a4c9e7d3b55 threadId: type: string description: Conversation thread id example: thread_2f81c04a context: type: array items: type: string description: Additional context messages to provide to the agent. example: - The customer is on the enterprise plan. variables: type: object additionalProperties: {} description: >- Values for {{variable}} placeholders in the agent's prompt blocks. Scalars (string, number, boolean) or arrays of them. A dot path up to 3 segments may be sent nested or as a dotted key — `{ "user": { "language": "FR" } }` and `{ "user.language": "FR" }` both fill `{{user.language}}`. This is the shape `GET /v1/copilots/{id}` and `GET /v1/agents/{id}` return under `variables`: fill in the leaves you have and send the object back. A null leaf is ignored (the placeholder falls back to its own default), so leaving one unfilled is the same as omitting it. Display-only — never used for authorization or identity. Reserved: `now.*`. Entries with an unsupported key or value are dropped, not rejected: a display-only field must not fail a chat turn. example: locale: English instance: store_count: 12 trigger: type: string enum: - submit-message - regenerate-message description: AI SDK trigger type tools: type: object additionalProperties: {} description: AI SDK client-side tools example: Acme_CRM_get_customer: enabled: true metadata: type: object additionalProperties: {} description: AI SDK session metadata example: source: web-widget use_routing: type: boolean default: true description: >- Default true. When the request targets an orchestrator agent, routing picks whether to stream the orchestrator (multi-step / synthesis) or a single subagent directly (domain-specific ask). No effect when the resolved agent is not an orchestrator. Pass false to disable. suggest_followups: type: boolean default: true description: >- Default true. After the answer finishes streaming, a small model proposes up to 3 questions the user could ask next, emitted as a `data-followups` chunk for the client to render as chips. Costs one extra model call per turn and holds the stream open slightly longer — pass false to disable. Only applies to copilotId requests: an agentId run has no UI to render chips into, so suggestions never run there. additionalProperties: false responses: '200': description: The finished turn content: application/json: schema: type: object properties: threadId: type: string description: >- The conversation this turn belongs to — the one you sent, or the one created for you. Send it back on the next call to continue. requestId: type: string nullable: true description: >- Correlation id for this run; the join key for its traces and cost. text: type: string description: The agent's answer. reasoning: type: string description: >- Reasoning text, when the model emitted any. Absent otherwise. toolCalls: type: array description: >- The tools the agent called, in order, each with its input and either its output or the error it failed with. items: type: object properties: toolCallId: type: string toolName: type: string input: type: object output: type: object error: type: string data: type: array description: >- Custom parts the run emitted: `data-handoff` (which agent a network routed to), `data-tool-workflow` (workflow step progress), and `data-tool-call-approval` — that last one means the run PAUSED for human approval rather than finishing. Call again with `approval` and the same `threadId` to continue it. items: type: object properties: type: type: string data: type: object errors: type: array description: >- Errors the run reported. A turn can fail after it began answering, so this can be non-empty alongside `text` — and the status is still 200, because the same failure over /v1/chat happens long after the headers. items: type: string finishReason: type: string '400': description: Invalid body, or no messages '403': description: Thread belongs to another organization '404': description: Agent or network not found '429': description: Usage limit exceeded security: - sessionToken: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Organization API key, generated in studio.sidenet.ai. Backend only — never in a browser. sessionToken: type: http scheme: bearer description: >- Session token (`snat_…`) minted by POST /v1/token. Carries the organization and the end user; safe in a browser. ````