Chat API: Multi-Turn Conversations with Your AI Agent

The Chat API lets you embed a fully conversational AI support experience anywhere in your product. Unlike the Query API, which handles single-shot questions, the Chat API maintains conversation context across multiple messages through the concept of a session. Each session has a unique session_id that ties all messages together, allowing your agent to understand follow-up questions, refer back to earlier context, and give coherent multi-turn responses. The typical flow is: create a session → send a message → receive a reply → send a follow-up → and so on, until the conversation is resolved.

You can pass "insights": true in any message request to generate conversation insights in your My AskAI dashboard. When Insights is enabled, each response also returns a conversation_id that you can include in subsequent requests to group them into a single conversation record.

Endpoint 1 — Create a Session

POST https://api.myaskai.com/v1/chat/sessions

Creates a new chat session and returns a session_id. Pass this ID in all subsequent message requests for this conversation.

Request Parameters

agent_id

string

required

The unique identifier of the My AskAI agent to use for this session. Find it in Settings → API.

user_id

string

An optional identifier for the end user. Used for analytics and personalisation via the User Data API.

Example Request

curl -X POST https://api.myaskai.com/v1/chat/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_abc123",
    "user_id": "usr_987"
  }'

Response Fields

session_id

string

A unique identifier for the newly created session. Pass this in all subsequent /messages calls.

created_at

string

ISO 8601 timestamp of when the session was created.

Example Response

{
  "session_id": "sess_x7k2m9p4",
  "created_at": "2024-10-15T09:30:00Z"
}

Endpoint 2 — Send a Message

POST https://api.myaskai.com/v1/chat/sessions/{session_id}/messages

Sends a user message within an existing session and returns the agent’s reply. The messages array you include should contain the full conversation history for this session — the API is stateless and does not store messages server-side between calls.

Path Parameters

session_id

string

required

The session_id returned when you created the session.

Request Parameters

messages

array

required

The full conversation history as an ordered array of message objects. Each object has:

messages[].role

string

required

Either "user" (messages from the end user) or "assistant" (replies from the AI agent).

messages[].content

string

required

The text content of the message.

insights

boolean

Set to true to log this conversation in your My AskAI dashboard Insights view. When enabled, the response includes a conversation_id.

conversation_id

string

Pass the conversation_id returned by a previous message request to link all API calls to a single conversation record in Insights.

Example Request — First Message

curl -X POST https://api.myaskai.com/v1/chat/sessions/sess_x7k2m9p4/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "How do I cancel my subscription?"
      }
    ],
    "insights": true
  }'

Example Request — Follow-up Message

curl -X POST https://api.myaskai.com/v1/chat/sessions/sess_x7k2m9p4/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "How do I cancel my subscription?"
      },
      {
        "role": "assistant",
        "content": "To cancel your subscription, email team@myaskai.com from your account email address."
      },
      {
        "role": "user",
        "content": "What happens to my data after I cancel?"
      }
    ],
    "insights": true,
    "conversation_id": "conv_jf83ls9"
  }'

Response Fields

object

The agent’s response message.

reply.role

string

Always "assistant".

reply.content

string

The text of the agent’s reply.

sources

array

Knowledge-base sources used to generate the reply.

sources[].title

string

Title of the source document.

sources[].url

string

URL of the source, if available.

unknown_answer

string

Set to "yes" if the agent couldn’t find a relevant answer. Also includes suggestedQuestions in this case.

suggestedQuestions

array

Returned alongside unknown_answer: "yes". Contains up to 3 alternative questions the agent is highly likely to be able to answer.

human_handover

boolean

true when a Guidance rule recommended escalation to a human agent.

conversation_id

string

Returned when insights is true. Pass this back in subsequent requests to link them to the same Insights record.

Example Response

{
  "reply": {
    "role": "assistant",
    "content": "To cancel your subscription, email team@myaskai.com from the email address associated with your account and the team will take care of everything for you."
  },
  "sources": [
    {
      "title": "Cancel subscription",
      "url": "https://help.myaskai.com/account-management/billing/cancel-subscription"
    }
  ],
  "conversation_id": "conv_jf83ls9"
}

Endpoint 3 — Retrieve Conversation History

GET https://api.myaskai.com/v1/chat/sessions/{session_id}/messages

Returns the full message history for a session. Useful for rendering a conversation in your UI or auditing past exchanges.

Path Parameters

session_id

string

required

The session whose message history you want to retrieve.

Example Request

curl -X GET https://api.myaskai.com/v1/chat/sessions/sess_x7k2m9p4/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Fields

session_id

string

The session identifier.

messages

array

Ordered array of all messages in the session.

messages[].role

string

"user" or "assistant".

messages[].content

string

Text content of the message.

messages[].created_at

string

ISO 8601 timestamp of when the message was sent.

Example Response

{
  "session_id": "sess_x7k2m9p4",
  "messages": [
    {
      "role": "user",
      "content": "How do I cancel my subscription?",
      "created_at": "2024-10-15T09:31:00Z"
    },
    {
      "role": "assistant",
      "content": "To cancel your subscription, email team@myaskai.com from the email address associated with your account.",
      "created_at": "2024-10-15T09:31:03Z"
    },
    {
      "role": "user",
      "content": "What happens to my data after I cancel?",
      "created_at": "2024-10-15T09:31:45Z"
    },
    {
      "role": "assistant",
      "content": "After cancellation your agent is deactivated at the end of the current billing period. Your data is retained for 30 days and then permanently deleted, unless you request earlier deletion.",
      "created_at": "2024-10-15T09:31:49Z"
    }
  ]
}

Error Codes

HTTP status	Description
`400 Bad Request`	Missing required field (`agent_id`, `messages`) or malformed request body.
`401 Unauthorized`	Missing or invalid API key.
`404 Not Found`	The `session_id` does not exist or has expired.
`429 Too Many Requests`	Rate limit exceeded.
`500 Internal Server Error`	Unexpected server error — retry with exponential back-off.

Sessions are not permanent. If you need to replay a conversation after a session expires, pass the full message history you stored client-side as the messages array in your next request to maintain context.

API Documentation

Chat API: Multi-Turn Conversations with Your AI Agent

Endpoint 1 — Create a Session

Request Parameters

Example Request

Response Fields

Example Response

Endpoint 2 — Send a Message

Path Parameters

Request Parameters

Example Request — First Message

Example Request — Follow-up Message

Response Fields

Example Response

Endpoint 3 — Retrieve Conversation History

Path Parameters

Example Request

Response Fields

Example Response

Error Codes

Build docs developers (and LLMs) love

API Documentation

Documentation Index

​Endpoint 1 — Create a Session

​Request Parameters

​Example Request

​Response Fields

​Example Response

​Endpoint 2 — Send a Message

​Path Parameters

​Request Parameters

​Example Request — First Message

​Example Request — Follow-up Message

​Response Fields

​Example Response

​Endpoint 3 — Retrieve Conversation History

​Path Parameters

​Example Request

​Response Fields

​Example Response

​Error Codes

Build docs developers (and LLMs) love

Endpoint 1 — Create a Session

Request Parameters

Example Request

Response Fields

Example Response

Endpoint 2 — Send a Message

Path Parameters

Request Parameters

Example Request — First Message

Example Request — Follow-up Message

Response Fields

Example Response

Endpoint 3 — Retrieve Conversation History

Path Parameters

Example Request

Response Fields

Example Response

Error Codes