> ## Documentation Index > Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt > Use this file to discover all available pages before exploring further. # Invoke an agent (start or continue a conversation) > Send a message to an agent and run it. This is how you invoke an agent programmatically — `POST /agents` only *builds* agents; this *runs* them. The agent must belong to the authenticated user's organization, and the org must have an API key configured for the agent's model provider (Control Hub → Providers) or the run will end with `streamStatus: "error"`. **Two response modes**, selected by the `X-Stream-Response` header: - **Non-streaming (recommended for API/automation)** — set `X-Stream-Response: false`. Returns **`202 Accepted`** immediately with `{ threadId, status: "in_progress" }` and an `X-Thread-ID` header, then runs the agent in the background. Poll `GET /getConversation?threadId={threadId}` until `streamStatus` is terminal (`completed` / `stopped` / `error` / `timeout`), then read the assistant message(s) from `messages`. This avoids platform request timeouts on long-running, multi-tool agents. - **Streaming** — omit the header (or send anything other than `false`). Returns **`200`** with a `text/event-stream` (AI SDK UI-message stream) and an `X-Thread-ID` header. Consume the SSE stream for incremental output. Most non-browser clients should prefer the non-streaming mode. **Conversation continuity:** omit `threadId` to start a new conversation (one is generated and returned in the `X-Thread-ID` header); pass an existing `threadId` to continue that thread. The message body uses the v5 `parts` format. ## OpenAPI ````yaml /openapi.yaml post /chat openapi: 3.1.0 info: title: AsterAgents API version: 1.0.0 description: > API for AsterAgents platform operations. - **Admin endpoints** (`/admin/*`) require organization admin privileges (`org:admin` role) - **Agent endpoints** (`/agents`) require agent management permissions or `org:admin` role - **Knowledge base endpoints** (`/kb/*`) require standard authentication - **Skills endpoints** (`/skills/*`) require standard authentication - **File endpoints** (`/upload/*`, `/kb/files`, `/skills/files`) require standard authentication contact: name: AsterAgents Support url: https://asteragents.com/support servers: - url: https://asteragents.com/api description: Production - url: http://localhost:3000/api description: Local development security: - bearerAuth: [] tags: - name: Users description: Manage active organization users - name: Invitations description: Manage organization invitations - name: Files description: Upload and manage files - name: Knowledge Bases description: Manage knowledge bases and their files - name: Knowledge Base Management description: Create, update, and delete knowledge bases - name: Agents description: Create, update, and delete agents - name: Agent Tags description: Organize agents with tags - name: Tools description: Discover the tool catalog available to your organization - name: Skills description: Manage agent skills - name: Skill Files description: Manage bundled files for skills - name: Conversations description: Invoke agents and retrieve conversation history and messages - name: Scheduled Tasks description: Schedule agents to run automatically on a cron schedule paths: /chat: post: tags: - Conversations summary: Invoke an agent (start or continue a conversation) description: > Send a message to an agent and run it. This is how you invoke an agent programmatically — `POST /agents` only *builds* agents; this *runs* them. The agent must belong to the authenticated user's organization, and the org must have an API key configured for the agent's model provider (Control Hub → Providers) or the run will end with `streamStatus: "error"`. **Two response modes**, selected by the `X-Stream-Response` header: - **Non-streaming (recommended for API/automation)** — set `X-Stream-Response: false`. Returns **`202 Accepted`** immediately with `{ threadId, status: "in_progress" }` and an `X-Thread-ID` header, then runs the agent in the background. Poll `GET /getConversation?threadId={threadId}` until `streamStatus` is terminal (`completed` / `stopped` / `error` / `timeout`), then read the assistant message(s) from `messages`. This avoids platform request timeouts on long-running, multi-tool agents. - **Streaming** — omit the header (or send anything other than `false`). Returns **`200`** with a `text/event-stream` (AI SDK UI-message stream) and an `X-Thread-ID` header. Consume the SSE stream for incremental output. Most non-browser clients should prefer the non-streaming mode. **Conversation continuity:** omit `threadId` to start a new conversation (one is generated and returned in the `X-Thread-ID` header); pass an existing `threadId` to continue that thread. The message body uses the v5 `parts` format. operationId: invokeAgent parameters: - name: X-Stream-Response in: header required: false description: >- Set to `false` for the non-streaming 202 + poll pattern. Any other value (or omitted) streams an SSE response. schema: type: string enum: - 'false' example: 'false' requestBody: required: true content: application/json: schema: type: object required: - agentId - message properties: agentId: type: integer description: >- ID of the agent to invoke (must belong to your organization). example: 123 message: type: object description: The user message in v5 format. required: - role - parts properties: role: type: string example: user parts: type: array description: >- Message content parts. Use a single text part for a plain message. items: type: object properties: type: type: string example: text text: type: string example: Summarize the latest quarterly report. threadId: type: string format: uuid nullable: true description: >- Existing conversation thread to continue. Omit to start a new conversation. example: 550e8400-e29b-41d4-a716-446655440000 timezone: type: string nullable: true description: >- IANA timezone used when rendering date/time prompt variables (e.g. "America/New_York"). examples: newConversation: summary: Start a new conversation value: agentId: 123 message: role: user parts: - type: text text: Summarize the latest quarterly report. continueConversation: summary: Continue an existing thread value: agentId: 123 threadId: 550e8400-e29b-41d4-a716-446655440000 message: role: user parts: - type: text text: Now compare it to the prior quarter. responses: '200': description: | Streaming mode (header omitted). A Server-Sent Events stream of the AI SDK UI-message protocol. The `X-Thread-ID` header carries the thread ID. headers: X-Thread-ID: description: The conversation thread ID. schema: type: string format: uuid content: text/event-stream: schema: type: string '202': description: > Accepted (non-streaming mode, `X-Stream-Response: false`). The agent runs in the background. Poll `GET /getConversation?threadId={threadId}` until `streamStatus` is terminal. headers: X-Thread-ID: description: The conversation thread ID (same as `threadId` in the body). schema: type: string format: uuid content: application/json: schema: type: object properties: threadId: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 status: type: string example: in_progress '400': description: Invalid request body, or message missing on a non-continuation call. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidBody: value: error: Invalid request body details: - path: agentId message: Required missingMessage: value: error: Message is required for non-continuation calls '401': description: Unauthorized (missing or expired API key). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized '404': description: Agent not found in your organization. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Agent not found or unauthorized '500': $ref: '#/components/responses/InternalServerError' components: schemas: Error: type: object required: - error properties: error: type: string example: Bad Request details: type: array items: type: object additionalProperties: true responses: InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Internal Server Error securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: | JWT token from Clerk authentication. Must be from a user with `org:admin` role. ````