curl --request POST \
  --url https://api.example.com/api/ai/v1/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "request": {
    "action": "send",
    "message": {
      "input": {
        "input": "Hello, introduce yourself briefly."
      }
    }
  },
  "options": {
    "xpertId": "YOUR_PUBLISHED_XPERT_ID"
  }
}
'

data: {"type":"event","event":"on_conversation_start","data":{"id":"conversation-id"}}

data: {"type":"message","data":"Hello"}

data: {"type":"event","event":"on_conversation_end","data":{"id":"conversation-id","status":"idle","error":null}}

data: {"type":"event","event":"on_conversation_start","data":{"id":"conversation-id"}}

data: {"type":"message","data":"Hello"}

data: {"type":"event","event":"on_conversation_end","data":{"id":"conversation-id","status":"idle","error":null}}

AI/v1

Chat with an agent

deprecated

This historical OpenAPI reference is no longer maintained and may not reflect current server behavior. New integrations should use the official XpertAI SDK (@xpert-ai/xpert-sdk): [SDK guide](/en/ai/agent/development-api). POST a message to a published agent and receive SSE. Historical request and response details are retained below for reference only. Authenticate with Authorization: Bearer <API_KEY> or x-api-key. Save on_conversation_start.data.id for continuation. Each SSE data field contains JSON with type, optional event, and data. Text deltas have type=message; lifecycle events have type=event. Inspect on_conversation_end.data.status/error and SSE error events: HTTP success alone does not mean the agent succeeded. Internal runtime options are not public caller fields.

POST

api

chat

curl --request POST \
  --url https://api.example.com/api/ai/v1/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "request": {
    "action": "send",
    "message": {
      "input": {
        "input": "Hello, introduce yourself briefly."
      }
    }
  },
  "options": {
    "xpertId": "YOUR_PUBLISHED_XPERT_ID"
  }
}
'

data: {"type":"event","event":"on_conversation_start","data":{"id":"conversation-id"}}

data: {"type":"message","data":"Hello"}

data: {"type":"event","event":"on_conversation_end","data":{"id":"conversation-id","status":"idle","error":null}}

data: {"type":"event","event":"on_conversation_start","data":{"id":"conversation-id"}}

data: {"type":"message","data":"Hello"}

data: {"type":"event","event":"on_conversation_end","data":{"id":"conversation-id","status":"idle","error":null}}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

request

object

required

Option 1
Option 2
Option 3
Option 4

Show child attributes

options

object

Public caller options. Tenant, organization, user and source are resolved by the server; never submit credentials or internal runtime objects here.

Show child attributes

Response

SSE stream. A connection close without on_conversation_end is incomplete. Ignore heartbeat comments and data frames whose trimmed value is : keep-alive before parsing JSON. Ignore unrelated lifecycle events.

The response is of type string.