> ## Documentation Index
> Fetch the complete documentation index at: https://support.myaskai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat API

Our Chat API allows a user to have a conversation with your AI agent via a simple API call. 

The **messages** array should contain the conversation between the user and the AI agent. You can send the entire conversation within the API request. 

Each message object has a **role** (user or assistant) and **content**. 

In the example below you can see a short conversation between a user and an AI agent. 

The message from the user has the **role: user** and all replies from the My AskAI have the **role: assistant**.

<Warning>
  If your AI agent doesn't know the answer, the API will also return an additional field to confirm an answer wasn't found as well as 3 suggested questions the user can retry (these have a very high likelihood of being answered correctly):&#x20;

  `"unknown_answer": "yes",`

  `"suggestedQuestions": ["Example question", ...]`
</Warning>

<Info>
  You can also pass in `"insights": true` to generate insights in your Dashboard from any API usage.&#x20;

  When Insights is enabled in the API a `conversation_id` is also returned with each request. This can be included in subsequent API requests to keep the requests link to 1 conversation. However, you still need to always pass in the message history as the API is stateless.
</Info>

<Info>
  If human handover [guidance](/features/improve/guidance) is triggered the API response will include: `"human_handover": true`
</Info>


## OpenAPI

````yaml /api-documentation/chat.yaml POST /ask-ai-chat
openapi: 3.0.0
info:
  title: AskAI Chat API
  version: '1.1'
servers:
  - url: https://myaskai.com/api/1.1/wf
security: []
paths:
  /ask-ai-chat:
    post:
      summary: Chat with AskAI
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: AskAI ID
                api_key:
                  type: string
                  description: AskAI API Key
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        description: Role in the conversation (user or assistant)
                      content:
                        type: string
                        description: Content of the message
              required:
                - id
                - api_key
                - messages
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  answer:
                    type: string
                    description: Answer from AskAI
                  references:
                    type: array
                    items:
                      type: object
                      properties:
                        content:
                          type: string
                          description: Content of the reference
                        link:
                          type: string
                          format: uri
                          description: Link to the reference
                        score:
                          type: number
                          format: float
                          description: Score of the reference
                        title:
                          type: string
                          description: Title of the reference

````