> ## Documentation Index > Fetch the complete documentation index at: https://docs.reygrid.com/llms.txt > Use this file to discover all available pages before exploring further. # Chat with an agent > Sends a message to an agent. When stream is false, the API returns a normal JSON response. When stream is true, the API returns a Server-Sent Events (SSE) stream using delta events. If userId is provided, it is used as the persistent conversation identifier and conversationId is ignored. ## OpenAPI ````yaml /openapi.yaml post /agents/{AgentId}/chat openapi: 3.0.3 info: title: ReyGrid API version: 1.0.3 description: | ReyGrid API ## Persistent user conversations If you want to build a separate conversation system for each user, build a wrapper layer around the ReyGrid API. The wrapper should manage the application's own user IDs and map them to ReyGrid conversations. The wrapper is responsible for: - Managing and identifying users. - Storing the relationship between the application's userId and ReyGrid conversationId. - Persisting conversation IDs in the application's own database. - Reusing the stored conversationId when the same user continues a conversation. - Verifying that conversation IDs belong to the expected user before using them. ReyGrid's userId can also be used as a stable identifier for persistent conversations. However, if the application requires its own user and conversation management, it should maintain this mapping in its own database. servers: - url: https://reygrid.com/api/v1 security: [] paths: /agents/{AgentId}/chat: post: summary: Chat with an agent description: | Sends a message to an agent. When stream is false, the API returns a normal JSON response. When stream is true, the API returns a Server-Sent Events (SSE) stream using delta events. If userId is provided, it is used as the persistent conversation identifier and conversationId is ignored. operationId: chatWithAgent parameters: - name: AgentId in: path required: true description: The ID of the agent. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatRequest' example: message: 'Where is my order #1042?' userId: user_42 responses: '200': description: Successful chat response content: application/json: schema: $ref: '#/components/schemas/ChatResponse' example: success: true userId: user_42 messageId: msg_mgGdMG8f9PUjc output: reply: id: msg_x6tWaZ3H9oOKd content: >- Your order #1042 shipped yesterday and should arrive within 2 business days. finish_reason: stop usage: credits: 0.5 text/event-stream: schema: type: string description: > Server-Sent Events stream returned when stream is true. The stream sends data-only SSE messages using the `data:` field. No explicit event field is sent. example: >+ data: {"success":true,"userId":"user_42","messageId":"msg_mgGdMG8f9PUjc","delta":{"reply":{"id":"msg_x6tWaZ3H9oOKd","content":"Your order"}},"usage":{"credits":0.5}} data: {"success":true,"userId":"user_42","messageId":"msg_mgGdMG8f9PUjc","delta":{"reply":{"id":"msg_x6tWaZ3H9oOKd","content":" shipped yesterday."},"finish_reason":"stop"},"usage":{"credits":0.5}} '400': description: >- Invalid request body (INVALID_BODY), or a message refused as harmful content (CONTENT_BLOCKED) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INVALID_BODY message: Invalid body list: message: - Message is required '401': description: API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/AuthErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNKNOWN_ERROR message: An error occurred output: {} usage: credits: 0 '503': description: >- The message couldn't be checked for harmful content (MODERATION_UNAVAILABLE). Nothing is charged; try again. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: MODERATION_UNAVAILABLE message: The message couldn't be checked. Try again in a moment. output: {} usage: credits: 0 security: - apiKeyAuth: [] x-codeSamples: - lang: bash label: cURL source: |- curl -X POST https://reygrid.com/api/v1/agents/{AgentId}/chat \ -H "Authorization: Bearer $REYGRID_API_KEY" \ -H "Content-Type: application/json" \ -d '{"message": "Where is my order #1042?", "userId": "user_42"}' - lang: python label: Python SDK source: >- from reygrid import ReyGrid client = ReyGrid(api_key="YOUR_API_KEY") res = client.chat("{AgentId}", "Where is my order #1042?", user_id="user_42") print(res.output.reply.content) # Streaming for event in client.stream_chat("{AgentId}", "Where is my order #1042?", user_id="user_42"): print(event.delta.reply.content or "", end="") - lang: javascript label: TypeScript SDK source: >- import { ReyGrid } from "reygrid"; const client = new ReyGrid({ apiKey: "YOUR_API_KEY" }); const res = await client.chat("{AgentId}", "Where is my order #1042?", { userId: "user_42" }); console.log(res.output.reply.content); // Streaming for await (const event of client.streamChat("{AgentId}", "Where is my order #1042?", { userId: "user_42" })) { process.stdout.write(event.delta?.reply?.content ?? ""); } components: schemas: ChatRequest: type: object required: - message properties: message: type: string example: Check my current subscription conversationId: type: string description: | Existing conversation ID. Ignored when userId is provided. example: conv_abc123 userId: type: string description: | Stable user identifier used to maintain a persistent conversation across platforms such as WhatsApp, Discord, and Telegram. When provided, conversationId is ignored. example: user_42 stream: type: boolean default: false description: | When true, the response is delivered using Server-Sent Events (SSE) with delta events. tools: type: array items: $ref: '#/components/schemas/Tool' results: type: array nullable: true minItems: 1 items: $ref: '#/components/schemas/ToolResult' ChatResponse: type: object required: - success - messageId - output - usage properties: success: type: boolean conversationId: type: string userId: type: string messageId: type: string output: $ref: '#/components/schemas/ChatOutput' usage: $ref: '#/components/schemas/ChatUsage' ErrorResponse: type: object required: - success - error properties: success: type: boolean output: type: object additionalProperties: true error: $ref: '#/components/schemas/Error' usage: $ref: '#/components/schemas/ChatUsage' AuthErrorResponse: type: object required: - error - code properties: error: type: string example: Unauthorized code: type: string example: AUTH_REQUIRED Tool: type: object required: - type - function properties: type: type: string enum: - function function: $ref: '#/components/schemas/FunctionDefinition' example: type: function function: name: check_subscription instructions: >- Opens the customer's current subscription plan, renewal date, and payment status. parameters: type: object properties: userId: type: string description: The customer's user id required: - userId ToolResult: type: object required: - toolCallId - output properties: toolCallId: type: string minLength: 1 output: type: string ChatOutput: type: object required: - reply - finish_reason properties: reply: $ref: '#/components/schemas/Reply' finish_reason: type: string ChatUsage: type: object required: - credits properties: credits: type: number Error: type: object required: - code - message properties: code: type: string message: type: string list: type: array description: | Validation error details. Present when error.code is INVALID_BODY. items: $ref: '#/components/schemas/ValidationErrorItem' FunctionDefinition: type: object required: - name properties: name: type: string minLength: 1 example: check_subscription instructions: type: string example: >- Opens the customer's current subscription plan, renewal date, and payment status. parameters: type: object additionalProperties: true example: type: object properties: userId: type: string description: The customer's user id required: - userId strict: type: boolean example: true Reply: type: object required: - id - content properties: id: type: string content: type: string ValidationErrorItem: type: object additionalProperties: true securitySchemes: apiKeyAuth: type: http scheme: bearer bearerFormat: API-Key description: ReyGrid API key sent as a Bearer token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.