> ## Documentation Index > Fetch the complete documentation index at: https://basedash.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Start a chat > Sends a message to the AI agent in a new chat, like sending the first message in the app. The response includes the new chat, your message, and the assistant message. The assistant responds asynchronously by default: use the `wait` parameter to receive the finished response directly, or poll the assistant message (or stream its events) after receiving HTTP 202. To continue the conversation, use "Send a follow-up message". ## OpenAPI ````yaml https://charts.basedash.com/api/public/openapi post /api/public/organizations/{orgId}/chats openapi: 3.1.0 info: title: Basedash Public API version: 0.0.0 description: >- API for programmatic access to Basedash features. Use API keys for authentication. contact: name: Basedash Support url: https://basedash.com email: support@basedash.com servers: - url: https://charts.basedash.com description: Production security: [] tags: - name: Organizations description: Manage organizations - name: Groups description: Manage organization groups and memberships - name: Data Sources description: Manage database connections and data sources - name: MCP servers description: Manage MCP server data sources - name: Insights description: Manage generated insights - name: Automations description: Manage automations and automation runs - name: Skills description: Manage organization skills - name: Definitions description: Manage reusable SQL definitions - name: Dashboards description: Manage dashboards and their tabs - name: Charts description: Manage charts and their SQL queries - name: Chats description: >- Chat with the Basedash AI agent about your data. Start a chat by sending a message, then continue the conversation with follow-up messages. The assistant responds asynchronously: pass the `wait` query parameter to receive the finished response in the same request, or poll the assistant message (or stream its events) after an HTTP 202. Chats created through the API are not shown in the Basedash app. paths: /api/public/organizations/{orgId}/chats: post: tags: - Chats summary: Start a chat description: >- Sends a message to the AI agent in a new chat, like sending the first message in the app. The response includes the new chat, your message, and the assistant message. The assistant responds asynchronously by default: use the `wait` parameter to receive the finished response directly, or poll the assistant message (or stream its events) after receiving HTTP 202. To continue the conversation, use "Send a follow-up message". parameters: - schema: type: string description: Organization ID required: true description: Organization ID name: orgId in: path - schema: type: integer minimum: 1 maximum: 300 description: >- Maximum number of seconds (1-300) to hold the request open while the assistant responds. If the response finishes in time the completed message is returned; otherwise the request returns HTTP 202 with the in-progress message. Omit to return immediately. required: false description: >- Maximum number of seconds (1-300) to hold the request open while the assistant responds. If the response finishes in time the completed message is returned; otherwise the request returns HTTP 202 with the in-progress message. Omit to return immediately. name: wait in: query - schema: type: string maxLength: 255 description: >- A unique key (up to 255 characters) that makes retries safe: repeating a request with the same key returns the original result instead of creating a duplicate. required: false description: >- A unique key (up to 255 characters) that makes retries safe: repeating a request with the same key returns the original result instead of creating a duplicate. name: Idempotency-Key in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePublicChatInput' responses: '200': description: >- The Idempotency-Key was already used, so the existing chat is returned instead of creating a duplicate content: application/json: schema: $ref: '#/components/schemas/PublicChatTurnResponse' '201': description: Chat created and the assistant finished responding content: application/json: schema: $ref: '#/components/schemas/PublicChatTurnResponse' '202': description: Chat created; the assistant is still responding content: application/json: schema: $ref: '#/components/schemas/PublicChatTurnResponse' '400': description: Bad request - Invalid JSON body or validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden - Organization trial has expired content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - Organization not found or no member access content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit exceeded - Too many requests content: application/json: schema: $ref: '#/components/schemas/RateLimitErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] components: schemas: CreatePublicChatInput: type: object properties: message: type: string minLength: 1 maxLength: 10000 description: >- The message to send to the AI agent, e.g. a question about your data. Maximum 10,000 characters. required: - message PublicChatTurnResponse: type: object properties: data: $ref: '#/components/schemas/PublicChatTurn' required: - data ErrorResponse: type: object properties: error: $ref: '#/components/schemas/ApiError' required: - error RateLimitErrorResponse: type: object properties: error: $ref: '#/components/schemas/RateLimitError' required: - error PublicChatTurn: type: object properties: chat: allOf: - $ref: '#/components/schemas/PublicChat' - description: The chat this exchange belongs to userMessage: $ref: '#/components/schemas/PublicChatMessage' assistantMessage: allOf: - $ref: '#/components/schemas/PublicChatMessage' - description: >- The assistant's response. Check its status to see whether it has finished responding. required: - chat - userMessage - assistantMessage ApiError: type: object properties: title: type: string description: Error type identifier detail: type: string description: Human-readable error description required: - title - detail RateLimitError: allOf: - $ref: '#/components/schemas/ApiError' - type: object properties: title: type: string enum: - RateLimitExceeded retryAfterMs: type: number description: Milliseconds until the rate limit window resets required: - retryAfterMs PublicChat: type: object properties: id: type: string description: Chat ID organizationId: type: string description: Organization ID name: type: string description: Chat name, generated automatically from the first message status: $ref: '#/components/schemas/PublicChatStatus' source: type: string enum: - api description: Chat creation source memberId: type: - string - 'null' description: Creating member ID createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - organizationId - name - status - source - memberId - createdAt - updatedAt PublicChatMessage: type: object properties: id: type: string description: Chat message ID chatId: type: string description: Chat ID role: type: string enum: - user - assistant description: Message author role status: $ref: '#/components/schemas/PublicChatMessageStatus' parentId: type: - string - 'null' description: User message ID associated with an assistant response text: type: string description: >- The message as plain text. For assistant messages this is the final answer, without reasoning or tool activity; see parts for the full structured content. parts: type: array items: $ref: '#/components/schemas/PublicChatContentPart' description: Ordered structured message content charts: type: array items: $ref: '#/components/schemas/PublicChatChart' description: Charts referenced by the assistant response createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - chatId - role - status - parentId - text - parts - charts - createdAt - updatedAt description: The message you sent PublicChatStatus: type: string enum: - generating - finished description: '`generating` while the assistant is responding, `finished` otherwise' PublicChatMessageStatus: type: string enum: - generating - finished - aborted - error - action_required description: >- `generating` while the assistant is responding, `finished` when the response is complete, `aborted` if it was canceled, `error` if it failed, and `action_required` if the assistant is waiting on a confirmation it cannot receive over the API PublicChatContentPart: type: object properties: id: type: string description: Content part ID type: type: string enum: - text - reasoning_summary - tool_call - tool_call_result - context - action - image - file description: Content part type content: type: string description: Text content or a JSON-encoded payload for structured part types externalId: type: - string - 'null' description: Provider item or tool call ID, when present name: type: - string - 'null' description: Tool or content part name phase: type: - string - 'null' enum: - commentary - final_answer - null description: Assistant response phase createdAt: type: string format: date-time description: Creation timestamp updatedAt: type: string format: date-time description: Last update timestamp required: - id - type - content - externalId - name - phase - createdAt - updatedAt PublicChatChart: type: object properties: chartId: type: string description: Chart ID chartVersionId: type: string description: Chart version ID title: type: string description: Chart title imageUrl: type: string format: uri description: >- URL that renders this chart as a PNG. Request it with the same API key authentication. mimeType: type: string description: Screenshot MIME type width: type: integer exclusiveMinimum: 0 description: Screenshot width height: type: integer exclusiveMinimum: 0 description: Screenshot height required: - chartId - chartVersionId - title - imageUrl - mimeType - width - height securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key authentication using Bearer token format: `Bearer ` ````