> ## Documentation Index > Fetch the complete documentation index at: https://developer.communicate.so/llms.txt > Use this file to discover all available pages before exploring further. # Send a chat turn to an agent > Creates or continues an API-channel conversation and returns one complete response payload. This endpoint does not stream. `requestId` is optional idempotency; reusing it with different input yields `409 request_id_conflict`. Chat turns are additionally rate-limited to 60 requests per minute per key. Responses may include grounded citations and, when an action ran, `actionName`. ## OpenAPI ````yaml https://app.communicate.so/api/v1/openapi.json post /agents/{agentId}/chat openapi: 3.1.0 info: title: Communicate Public REST API version: 1.0.0 summary: >- Workspace-scoped agent listing and chat operations with least-privilege OAuth scopes. description: >- Canonical external schema for the non-streaming public REST API. Exchange a workspace API-key client ID and secret for a short-lived OAuth access token, or use the `ck_` key directly for backward compatibility. `requestId` is optional but, when supplied, becomes the idempotency key for retries of the same chat input. servers: - url: https://app.communicate.so/api/v1 description: Canonical external base URL served through the Next.js /api/v1 rewrite. security: - oauth2: [] - bearerAuth: [] paths: /agents/{agentId}/chat: post: tags: - Chat summary: Send a chat turn to an agent description: >- Creates or continues an API-channel conversation and returns one complete response payload. This endpoint does not stream. `requestId` is optional idempotency; reusing it with different input yields `409 request_id_conflict`. Chat turns are additionally rate-limited to 60 requests per minute per key. Responses may include grounded citations and, when an action ran, `actionName`. operationId: chatWithAgent parameters: - name: agentId in: path required: true description: The target agent identifier. schema: type: string minLength: 1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatRequest' responses: '200': description: Completed non-streaming chat response headers: RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ChatResponse' '400': description: Malformed JSON or invalid request body content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid API key headers: WWW-Authenticate: schema: type: string description: Bearer challenge describing the API-key authentication failure. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '402': description: >- Chat generation is unavailable because billing is paused or credits are exhausted content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Credential does not grant `chat:write` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Agent not found in the API key workspace content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Agent is inactive, or requestId was replayed with different input content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: API key rate limit exceeded headers: RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Unexpected server failure content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Agent is mid-transfer and temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - oauth2: - chat:write - bearerAuth: [] components: schemas: ChatRequest: type: object additionalProperties: false required: - message properties: message: type: string minLength: 1 maxLength: 4000 description: End-user prompt sent to the agent. requestId: type: string format: uuid description: Optional idempotency key for safe retries of the same chat input. conversationId: type: - string - 'null' description: Continue an existing API-channel conversation when present. ChatResponse: type: object additionalProperties: false required: - conversationId - messageId - userMessageId - answer - citations - mode properties: conversationId: type: string ticketNumber: type: - integer - 'null' messageId: type: string userMessageId: type: string answer: type: string citations: type: array items: $ref: '#/components/schemas/Citation' mode: type: string enum: - ai - human actionName: type: string description: Present when a workspace action produced the final answer. followUps: type: array items: type: string maxItems: 3 description: Optional suggested next questions returned with the answer. ErrorResponse: type: object additionalProperties: false required: - error - code properties: error: type: string code: type: string reason: type: string details: type: array items: type: object additionalProperties: false required: - code - message - path properties: code: type: string message: type: string path: type: string Citation: type: object additionalProperties: false required: - sourceId - title - snippet - url properties: sourceId: type: string title: type: string snippet: type: string url: type: - string - 'null' headers: RateLimitLimit: description: Maximum requests allowed in the active one-minute window. schema: type: integer minimum: 1 RateLimitRemaining: description: Requests remaining in the active one-minute window. schema: type: integer minimum: 0 RateLimitReset: description: Seconds until the active rate-limit window resets. schema: type: integer minimum: 1 securitySchemes: oauth2: type: oauth2 description: >- OAuth 2.0 client-credentials tokens bounded by the source API key scope ceiling. flows: clientCredentials: tokenUrl: https://app.communicate.so/api/v1/oauth/token scopes: agents:read: List agents in the authenticated workspace. chat:write: Create chat turns with an agent in the authenticated workspace. bearerAuth: type: http scheme: bearer bearerFormat: API key description: Workspace API key token with the `ck_` prefix. ````