Bots & chat

Create a bot

POST /bots
x-lex-client: my-app
Content-Type: application/json

{
  "name": "Research Assistant",
  "description": "Finds and summarises sources",
  "defaultMode": "cendikia",
  "instructions": "Answer in Bahasa Indonesia. Cite your sources.",
  "character": { "outfit": "pro", "hat": "#4A8FE0", "accessory": "glasses" }
}

Field	Notes
name	1–80 characters
defaultMode	nalar (quick), patih (balanced, default) or cendikia (deep)
instructions	Up to 8,000 characters. They can't override workspace security policy.
character	The bot's Lex: outfit (default, casual, pro, cool, female), hat (hex colour for hat, boots and scarf), accessory (none, glasses, sunglasses)

Other bot endpoints: GET /bots, GET /bots/{botId}, PATCH /bots/{botId}, DELETE /bots/{botId} (archive), POST /bots/{botId}/restore, GET /bots/archived and DELETE /bots/{botId}/permanent. Deleting a bot permanently stops anything it is still running.

One chat per bot

Each bot has a single, continuous chat thread per user.

• GET /chats lists every bot's chat with its last message (for a sidebar).
• GET /chats/thread?botId=… returns the bot's thread, creating it on first use.
• GET /conversations/{conversationId}/messages returns its messages, oldest first.
• DELETE /chats/thread/messages?botId=… clears the chat (and stops a reply in progress).

Send a message

POST /agent-runs
x-lex-client: my-app
Content-Type: application/json

{ "botId": "bot_123", "message": "Summarise this week's sales emails", "mode": "patih" }

{ "runId": "run_456", "conversationId": "conv_789", "status": "queued", "eventsUrl": "/api/v1/agent-runs/run_456/events" }

Field	Notes
message	1–20,000 characters
botId	The bot to talk to. The message goes into that bot's thread.
mode	Overrides the bot's default for this message
attachmentIds	Files uploaded beforehand, see Attachments & tags
mentions	Connectors, plugins or Mini Programs to use, see Attachments & tags

Then follow the run for the reply. When it finishes, the reply is also saved as an assistant message in the thread.

Run lifecycle

queued → running ⇄ waiting_for_approval → completed
                                         ↘ failed | cancelled | timed_out

• GET /agent-runs/{runId} returns the run with its status, output and lastEventSeq.
• POST /agent-runs/{runId}/cancel stops it.
• GET /agent-runs/{runId}/tool-executions lists the tools it used.
• GET /agent-runs?botId=… lists recent runs.