> ## Documentation Index > Fetch the complete documentation index at: https://docs.vyomflow.co.in/llms.txt > Use this file to discover all available pages before exploring further. # Submit a message and start (or continue) an agent turn > Same Turn Lifecycle as the internal route, plus an optional `Idempotency-Key` header — a retried request presenting the same key for this chat replays the original turn's current state rather than charging credits or dispatching twice. Response omits the raw Trigger.dev realtime token; `stream.url` points at this API's own SSE endpoint instead. ## OpenAPI ````yaml /openapi.json post /api/public/v1/chats/{chatId}/messages openapi: 3.1.0 info: title: VyomFlow API version: 1.0.0 description: >- The versioned public REST surface (`/api/public/v1/*`, bearer API-key auth) plus the app's own internal `/api/v1/*` surface (Clerk session-token auth), generated directly from the same Zod contracts the Route Handlers validate against — never a hand-maintained duplicate. The MCP endpoint (`/api/mcp`) is a separate streamable-HTTP JSON-RPC transport, not expressible here — see the MCP guide. servers: - url: https://api.vyomflow.co.in description: Production - url: http://localhost:3000 description: Local development security: [] paths: /api/public/v1/chats/{chatId}/messages: post: tags: - Public API summary: Submit a message and start (or continue) an agent turn description: >- Same Turn Lifecycle as the internal route, plus an optional `Idempotency-Key` header — a retried request presenting the same key for this chat replays the original turn's current state rather than charging credits or dispatching twice. Response omits the raw Trigger.dev realtime token; `stream.url` points at this API's own SSE endpoint instead. parameters: - schema: type: string minLength: 1 required: true name: chatId in: path - schema: type: string required: false name: Idempotency-Key in: header requestBody: content: application/json: schema: type: object properties: content: type: array items: oneOf: - type: object properties: type: type: string enum: - text text: type: string required: - type - text - type: object properties: type: type: string enum: - thinking text: type: string required: - type - text - type: object properties: type: type: string enum: - tool_use id: type: string name: type: string input: type: object additionalProperties: {} required: - type - id - name - input - type: object properties: type: type: string enum: - tool_result toolUseId: type: string output: {} isError: type: boolean toolInvocationId: type: string name: type: string status: type: string enum: - DISPATCHING - QUEUED - RUNNING - COMPLETED - FAILED - CANCELLED durationMs: type: integer minimum: 0 creditUsed: type: number minimum: 0 resultUrls: type: array items: type: string format: uri errorMessage: type: string errorCode: type: string required: - type - toolUseId - type: object properties: type: type: string enum: - reasoning text: type: string required: - type - text - type: object properties: type: type: string enum: - citation url: type: string format: uri title: type: string required: - type - url - type: object properties: type: type: string enum: - usage promptTokens: type: integer minimum: 0 completionTokens: type: integer minimum: 0 model: type: string costCredits: type: number minimum: 0 required: - type - promptTokens - completionTokens attachments: type: array items: type: object properties: id: type: string required: - id maxItems: 10 default: [] model: type: string minLength: 1 required: - content responses: '201': description: >- Message persisted and turn dispatched (or the replayed prior result). content: application/json: schema: $ref: '#/components/schemas/PublicSendTurnResponse' '400': description: Malformed request body. content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/ApiError' '402': description: Insufficient credits to start this turn. content: application/json: schema: $ref: '#/components/schemas/ApiError' '403': description: Valid key missing the required `runs:write` scope. content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Not found (non-leaking — see above). content: application/json: schema: $ref: '#/components/schemas/ApiError' '409': description: A run is already active on this chat. content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: >- Per-API-key rate limit exceeded (`X-RateLimit-*`/`Retry-After` headers set). content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: >- The Trigger.dev dispatch call itself failed; the turn was not started. content: application/json: schema: $ref: '#/components/schemas/ApiError' security: - ApiKeyAuth: - runs:write components: schemas: PublicSendTurnResponse: type: object properties: chatId: type: string message: type: object properties: id: type: string chatId: type: string role: type: string enum: - user - assistant - system - tool status: type: string enum: - streaming - complete - failed - cancelled content: type: array items: oneOf: - type: object properties: type: type: string enum: - text text: type: string required: - type - text - type: object properties: type: type: string enum: - thinking text: type: string required: - type - text - type: object properties: type: type: string enum: - tool_use id: type: string name: type: string input: type: object additionalProperties: {} required: - type - id - name - input - type: object properties: type: type: string enum: - tool_result toolUseId: type: string output: {} isError: type: boolean toolInvocationId: type: string name: type: string status: type: string enum: - DISPATCHING - QUEUED - RUNNING - COMPLETED - FAILED - CANCELLED durationMs: type: integer minimum: 0 creditUsed: type: number minimum: 0 resultUrls: type: array items: type: string format: uri errorMessage: type: string errorCode: type: string required: - type - toolUseId - type: object properties: type: type: string enum: - reasoning text: type: string required: - type - text - type: object properties: type: type: string enum: - citation url: type: string format: uri title: type: string required: - type - url - type: object properties: type: type: string enum: - usage promptTokens: type: integer minimum: 0 completionTokens: type: integer minimum: 0 model: type: string costCredits: type: number minimum: 0 required: - type - promptTokens - completionTokens attachments: type: array items: type: object properties: id: type: string chatId: type: - string - 'null' messageId: type: - string - 'null' orderIndex: type: integer minimum: 0 status: type: string enum: - PENDING - READY - FAILED - CANCELLED mimeType: type: - string - 'null' byteSize: type: - integer - 'null' minimum: 0 fileName: type: - string - 'null' resultUrl: type: - string - 'null' format: uri errorCode: type: - string - 'null' errorMessage: type: - string - 'null' createdAt: type: string updatedAt: type: string source: type: string enum: - uploaded - generated required: - id - chatId - messageId - orderIndex - status - mimeType - byteSize - fileName - resultUrl - errorCode - errorMessage - createdAt - updatedAt - source createdAt: type: string required: - id - chatId - role - status - content - attachments - createdAt run: type: object properties: id: type: string chatId: type: string status: type: string enum: - queued - running - waiting - completed - failed - cancelled userMessageId: type: string assistantMessageId: type: - string - 'null' lastStreamIndex: type: integer cancelRequestedAt: type: - string - 'null' requestedModel: type: string resolvedModel: type: - string - 'null' errorCode: type: - string - 'null' errorMessage: type: - string - 'null' createdAt: type: string updatedAt: type: string startedAt: type: - string - 'null' finishedAt: type: - string - 'null' toolInvocations: type: array items: type: object properties: id: type: string agentRunId: type: string turnIndex: type: integer minimum: 0 callIndex: type: integer minimum: 0 toolCallId: type: string name: type: string nodeType: type: string input: type: object additionalProperties: {} status: type: string enum: - DISPATCHING - QUEUED - RUNNING - COMPLETED - FAILED - CANCELLED creditEstimate: type: - number - 'null' minimum: 0 creditUsed: type: - number - 'null' minimum: 0 resultUrls: type: - array - 'null' items: type: string format: uri errorCode: type: - string - 'null' errorMessage: type: - string - 'null' startedAt: type: - string - 'null' finishedAt: type: - string - 'null' durationMs: type: - integer - 'null' minimum: 0 createdAt: type: string updatedAt: type: string required: - id - agentRunId - turnIndex - callIndex - toolCallId - name - nodeType - input - status - creditEstimate - creditUsed - resultUrls - errorCode - errorMessage - startedAt - finishedAt - durationMs - createdAt - updatedAt totalCreditsUsed: type: number minimum: 0 pendingWaitpoint: oneOf: - type: object properties: id: type: string agentRunId: type: string kind: type: string enum: - CREDIT_APPROVAL status: type: string enum: - PENDING - COMPLETED - EXPIRED requestPayload: type: object properties: toolName: type: string estimatedCredits: type: number minimum: 0 threshold: type: number minimum: 0 required: - toolName - estimatedCredits - threshold resolvedPayload: type: - object - 'null' properties: approved: type: boolean respondedAt: type: string required: - approved - respondedAt expiresAt: type: string resolvedAt: type: - string - 'null' required: - id - agentRunId - kind - status - requestPayload - resolvedPayload - expiresAt - resolvedAt - type: object properties: id: type: string agentRunId: type: string kind: type: string enum: - CLARIFICATION status: type: string enum: - PENDING - COMPLETED - EXPIRED requestPayload: type: object properties: question: type: string options: type: array items: type: string required: - question resolvedPayload: type: - object - 'null' properties: answer: type: string respondedAt: type: string required: - answer - respondedAt expiresAt: type: string resolvedAt: type: - string - 'null' required: - id - agentRunId - kind - status - requestPayload - resolvedPayload - expiresAt - resolvedAt - type: 'null' required: - id - chatId - status - userMessageId - assistantMessageId - lastStreamIndex - cancelRequestedAt - requestedModel - resolvedModel - errorCode - errorMessage - createdAt - updatedAt - startedAt - finishedAt - toolInvocations - totalCreditsUsed - pendingWaitpoint stream: type: object properties: url: type: string fromIndex: type: integer minimum: 0 required: - url - fromIndex required: - chatId - message - run - stream ApiError: type: object properties: error: type: object properties: code: type: string message: type: string details: {} required: - code - message required: - error securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- Clerk-native API key, `Authorization: Bearer `. Minted at https://www.vyomflow.co.in/settings/api-keys, scoped per operation. 401 = missing/invalid/revoked key; 403 = valid key missing the required scope. ````