> ## Documentation Index > Fetch the complete documentation index at: https://developers.arg.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start an agent run > Run one agent turn. Returns `200` with `job_id` and `call_id` when the turn starts, or `202` with `queue_id` and `position` when a turn is already running on the chat and this one was queued behind it. The turn executes in the background - poll `GET /api/agent/status/{callId}` for the result. ## OpenAPI ````yaml POST /api/agent/message openapi: 3.0.3 info: title: arg.ai API version: 0.1.0 description: >- The workspace for teams and agents: files, a sandbox to run code in, and agents that work in both. Authenticate with an API key in the `X-API-Key` header, or a user access token in `Authorization: Bearer`. A handful of account-level routes accept a user session only; each says so. Errors are JSON objects with a `detail` string and the matching HTTP status. servers: - url: https://api.arg.ai security: [] tags: - name: .well-known description: Discovery documents for MCP client authorization. - name: action-runs description: Cross-workspace Action run history. - name: actions description: Discover and run Actions - the typed capability catalog agents call. - name: actions-exec description: Token-authenticated Action execution for sandboxes, sites and servers. - name: agent description: Start agent runs, watch them, steer the queue, and stop them. - name: auth description: Authenticated user, profile, and session endpoints. - name: automation description: Deploy, trigger, and inspect automations. - name: chats description: 'Chat records: list, read, rename, pin, archive, and delete.' - name: connectors description: Bring-your-own MCP connectors and their credentials. - name: file-invitations description: file-invitations endpoints. - name: files description: files endpoints. - name: git-repos description: git-repos endpoints. - name: health description: Service health and metadata. - name: integrations description: Third-party integration connections and their OAuth flows. - name: keys description: API keys for programmatic access. - name: loops description: loops endpoints. - name: mcp description: Model Context Protocol endpoints for MCP clients. - name: models description: Available models and per-organization model settings. - name: notifications description: Notifications and delivery preferences. - name: oauth description: OAuth 2.1 authorization server used by MCP clients. - name: organizations description: Organizations, members, roles, invitations, and billing. - name: service-accounts description: Non-human identities that own API keys. - name: share description: Share links, public file access, and invitations. - name: site-access description: site-access endpoints. - name: sites description: Hosted sites built from a workspace folder. - name: templates description: Publish and clone workspace templates. - name: tunnel-access description: tunnel-access endpoints. - name: tunnels description: 'Servers: long-running processes exposed on an HTTPS URL.' - name: workspaces description: Workspaces, files, tools, search, and workspace-scoped features. paths: /api/agent/message: post: tags: - agent summary: Start an agent run description: >- Run one agent turn. Returns `200` with `job_id` and `call_id` when the turn starts, or `202` with `queue_id` and `position` when a turn is already running on the chat and this one was queued behind it. The turn executes in the background - poll `GET /api/agent/status/{callId}` for the result. operationId: postApiAgentMessage parameters: [] requestBody: description: >- Send `message` for plain text. `chat_id` is optional - omit it and a new chat is created on the first send. required: true content: application/json: schema: type: object properties: message: type: string description: The user message to run. Required unless you send `parts`. chat_id: type: string description: Chat to run the turn on. A new chat is created when omitted. workspace_id: type: string description: >- Workspace the agent works in. Without it the agent has no files and no sandbox. organization_id: type: string description: >- Organization context. Defaults to the credential's organization. model: type: string description: >- Model id, for example `anthropic/claude-haiku-4.5`. Defaults per organization. reasoning_effort: type: string description: >- Reasoning depth. Clamped to what the selected model supports. enum: - none - low - medium - high max_tool_iterations: type: integer description: Maximum tool-use rounds for this turn, from 1 to 100. read_only: type: boolean description: >- Run with read-only tools, so the turn cannot modify the workspace. disabled_skills: type: array description: Workspace skill names to withhold from this turn. items: type: string disabled_agents: type: array description: Subagent names to withhold from this turn. items: type: string message_id: type: string description: >- Client-supplied UUID for the user message. Generated when omitted. required: - message responses: '200': description: Successful response content: application/json: schema: type: object additionalProperties: true default: description: Error response content: application/json: schema: type: object properties: detail: type: string security: - bearerAuth: [] - apiKeyAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT apiKeyAuth: type: apiKey in: header name: x-api-key ````