> ## Documentation Index > Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run an agent (streaming or one-shot) > Dispatches an agent run by `executionMode`: - `in_sandbox` — routes through the linked sandbox runtime. - `managed` — routes into `runtools-model-gateway`. - `local-mac` — registers and dispatches through RunMesh to the bound device. Streaming responses are `text/event-stream` (SSE) with RunTools agent event frames. Non-streaming returns JSON when complete. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/run openapi: 3.1.0 info: title: RunTools API version: 1.0.0 description: | The RunTools platform API for cloud sandboxes, agents, workspaces, tools, threads, billing, and credentials. This document covers the customer-facing surface across six services: - api.runtools.ai — orchestrator (control plane) - auth.runtools.ai — auth service (API keys, SSH keys, OAuth, secrets) - tools.runtools.ai — tool marketplace + execution - billing.runtools.ai — credits, top-up, auto-top-up - storage.runtools.ai — workspace file APIs Internal-only routes (`/internal/*`, admin routes, webhooks), as well as deferred/gated surfaces (workflows, snapshots, rollback, code-exec), are deliberately excluded. ## Authentication Two auth schemes are supported on the public surface: - **WorkOS session token** — Bearer token from interactive login, used by dashboard, mobile, CLI `login`, Mac app, and any browser-driven flow. - **API key** — `rt_live_*` or `rt_test_*` keys created via `POST /v1/api-keys`. Scope-checked at each handler. Either may be passed in `Authorization: Bearer ` or, for API keys, in `X-API-Key`. ## Response envelope Most successful JSON responses wrap data in `{ "data": ... }`. Paginated responses additionally carry `hasMore` and `nextCursor`. Error responses use `{ "error": { "code": "...", "message": "..." } }`. ## Versioning header Every public response includes an `X-API-Version: v1` header. This is the contract for clients that want to assert the surface version they were written against. A future `/v2/*` rollout will set `X-API-Version: v2` on matching responses while `/v1/*` continues to return `v1`. contact: name: RunTools url: https://runtools.ai license: name: Proprietary servers: - url: https://api.runtools.ai description: Orchestrator (control plane) - url: https://auth.runtools.ai description: Auth service - url: https://tools.runtools.ai description: Tools service - url: https://billing.runtools.ai description: Billing service - url: https://storage.runtools.ai description: Storage service (workspace files) security: - bearer: [] - apiKey: [] tags: - name: Health description: Liveness and readiness probes. - name: Profile description: Current user profile. - name: Organizations description: Organization CRUD, members, tool-install policy. - name: Projects description: Org-scoped projects and resource pins. - name: Sandboxes description: Firecracker microVM lifecycle, exec, URLs, SSH/VNC. - name: Agents description: Agent definitions and CRUD. - name: Agent marketplace description: Public marketplace listing and install. - name: Agent runs description: Dispatch and observe agent runs. - name: Channels description: External messaging channels and channel privacy. - name: Threads description: Public thread storage (JSONL-backed). - name: Workspaces description: Workspace metadata and usage (control plane). - name: Workspace files description: NFS-backed workspace file APIs (storage service). - name: Installable agents description: Hermes catalog and install lifecycle. - name: Attachments description: Agent message attachments (uploaded files). - name: Tools (marketplace) description: Public tool marketplace and schemas. - name: Tools (installed) description: Org tool installs and credentials. - name: Tools (custom) description: Org-private custom tool CRUD and publishing. - name: Tool execution description: Server-side tool invocation. - name: Secrets description: Encrypted secrets (org-scoped). - name: SSH keys description: SSH key CRUD for sandbox access. - name: API keys description: API key issuance and revocation. - name: OAuth connections description: User OAuth connections to providers. - name: BYOA configs description: Bring-your-own-app OAuth client configuration. - name: LangTerm description: LangTerm SSH connection profiles. - name: Models description: Available model registry. - name: Model proxy description: Platform-tier model invocation. - name: Calendar description: Google Calendar connections. - name: RunMesh description: RunMesh device pairing and management. - name: Terminal description: Browser terminal session minting. - name: Activity description: Customer-facing activity event log. - name: Billing description: Credits, top-up, auto-top-up, usage pricing. - name: Auth description: Token verification and logout URLs. paths: /v1/run: post: tags: - Agent runs summary: Run an agent (streaming or one-shot) description: | Dispatches an agent run by `executionMode`: - `in_sandbox` — routes through the linked sandbox runtime. - `managed` — routes into `runtools-model-gateway`. - `local-mac` — registers and dispatches through RunMesh to the bound device. Streaming responses are `text/event-stream` (SSE) with RunTools agent event frames. Non-streaming returns JSON when complete. operationId: runAgent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentRunRequest' responses: '200': description: Run completed (non-streaming) or registered (local-mac caller). content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/AgentRunResponse' text/event-stream: schema: type: string description: SSE stream of `ThreadEventFrame` payloads. '402': description: Insufficient credits. '404': description: Agent not found or `RUNMESH_NOT_REGISTERED` for local-mac. '409': description: Thread is busy with an in-flight run. servers: - url: https://api.runtools.ai components: schemas: AgentRunRequest: type: object required: - agent properties: agent: type: string description: Agent slug or UUID. prompt: type: string stream: type: boolean default: true messages: type: array items: $ref: '#/components/schemas/Message' threadId: type: string description: Optional thread ID for server-managed conversation persistence. config: type: object properties: maxTokens: type: integer maxTurns: type: integer temperature: type: number metadata: type: object additionalProperties: true AgentRunResponse: type: object properties: runId: type: string format: uuid sandboxId: type: string nullable: true threadId: type: string nullable: true rolloutId: type: string nullable: true executionMode: $ref: '#/components/schemas/AgentExecutionMode' targetDeviceId: type: string nullable: true status: type: string enum: - registered - dispatched - completed - failed - cancelled - running result: description: Final assistant message or structured output. usage: $ref: '#/components/schemas/AgentRunUsage' iterations: type: integer Message: type: object properties: role: type: string enum: - user - assistant - system content: type: string nullable: true parts: type: array items: $ref: '#/components/schemas/MessagePart' AgentExecutionMode: type: string enum: - in_sandbox - managed - local-mac AgentRunUsage: type: object properties: promptTokens: type: integer completionTokens: type: integer totalTokens: type: integer inputTokens: type: integer outputTokens: type: integer cachedInputTokens: type: integer reasoningTokens: type: integer MessagePart: oneOf: - $ref: '#/components/schemas/MessagePartText' - $ref: '#/components/schemas/MessagePartAttachment' - $ref: '#/components/schemas/MessagePartFile' - $ref: '#/components/schemas/MessagePartSource' MessagePartText: type: object properties: type: type: string enum: - text text: type: string required: - type - text MessagePartAttachment: type: object properties: type: type: string enum: - attachment attachmentId: type: string format: uuid filename: type: string nullable: true contentType: type: string nullable: true MessagePartFile: type: object properties: type: type: string enum: - file path: type: string contentType: type: string nullable: true MessagePartSource: type: object properties: type: type: string enum: - source url: type: string title: type: string nullable: true securitySchemes: bearer: type: http scheme: bearer description: | WorkOS session token or RunTools API key (`rt_live_*` / `rt_test_*`). Used in `Authorization: Bearer ` header. apiKey: type: apiKey in: header name: X-API-Key description: Alternative location for a RunTools API key (`rt_live_*` / `rt_test_*`). ````