Start a widget thread for a visitor

POST

widget

conversations

// Runs on your website. The widget key is public and belongs in page source.
const MITHUNAI_API = `${MITHUNAI_URL}/arukz/api/v1`
const WIDGET_KEY = 'arukz_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e'

const response = await fetch(`${MITHUNAI_API}/widget/conversations`, {
  method: 'POST',
  headers: {
    'X-ARUKZ-Widget-Key': WIDGET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ metadata: { page: window.location.pathname } }),
})
const { conversation, visitor_token } = await response.json()

// Keep both for this thread. The token cannot be fetched again.
sessionStorage.setItem('mithunai.conversation', conversation.id)
sessionStorage.setItem('mithunai.visitorToken', visitor_token)

curl --request POST "$MITHUNAI_URL/arukz/api/v1/widget/conversations" \
  --header "X-ARUKZ-Widget-Key: arukz_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" \
  --header "Origin: https://docs.example.com" \
  --header "Content-Type: application/json" \
  --data '{"metadata": {"page": "/guides/rate-limits"}}'

{
  "conversation": {
    "id": "0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a",
    "assistant_id": "5b1e9c2a-7d4f-4e3b-9a61-0c8f2d7e4a13",
    "title": "New conversation",
    "status": "active",
    "turn_state": "idle",
    "message_count": 0,
    "created_at": "2026-09-24T10:02:17.559310+00:00",
    "updated_at": "2026-09-24T10:02:17.559310+00:00",
    "owner": { "type": "widget", "id": "8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" },
    "metadata": { "page": "/guides/rate-limits" }
  },
  "visitor_token": "5Ex151H7YDPzbzcCdGkgXUzttBDjF1q0OtEG5jfi-OM"
}

{ "code": "validation_error", "message": "That metadata key is reserved." }

{ "code": "authentication_error", "message": "Authentication is required." }

{ "code": "authorization_error", "message": "This widget may not be embedded from that origin." }

{ "code": "rate_limit_exceeded", "message": "Too many requests. Please retry later." }

Call this from the visitor’s browser. It does not take an API key or a console session. It takes the embed’s public widget key in the X-ARUKZ-Widget-Key header, and the browser’s Origin must be allowed by both the deployment’s allowed_origins and the platform-wide widget allowlist. See Website widget. The response contains a visitor_token. It is returned once, in this response, and cannot be retrieved again: only its hash is stored. Keep it for the life of the thread (for example in sessionStorage) and send it as X-ARUKZ-Visitor-Token on every later request about this conversation. Every visitor on your site shares the same widget key, so the visitor token is what stops one visitor reading another’s conversation. The assistant is always the one the deployment embeds. An assistant_id in the body is ignored and replaced; you cannot point a widget at a different assistant. The conversation starts empty; ask the first question with Send a widget message. The body must be a JSON object. Send {} when you have no title or metadata. When a request is refused, the response carries no Access-Control-Allow-Origin header, so in a cross-origin browser request fetch rejects with a network error instead of exposing the error body.

The deployment’s public widget key, arukz_wk_….

string

required

Set by the browser. It must exactly match an origin allowed for this deployment. When you call from outside a browser, set it yourself.

string

A title for the thread, up to 200 characters. When omitted, the thread is titled New conversation until the first question renames it.

object

Your own string labels for the thread, such as the page it started on. At most 20 entries. Keys are 1 to 64 characters, start with a lowercase letter and contain only a-z, 0-9, _, . and -. Values are strings of up to 512 characters. Do not use keys beginning with arukz.: they are reserved for the platform and are never returned in responses.

Response

Returns 201 Created.

object

required

The new conversation.

Show properties

string

required

The conversation’s ID (UUID).

string

required

The assistant the deployment embeds.

string

required

The title you sent, or New conversation.

string

required

active.

string

required

idle: ready for a question.

integer

required

0.

string

required

ISO 8601 in UTC.

string

required

ISO 8601 in UTC.

object

required

{"type": "widget", "id": <deployment ID>}. All threads of one embed share this owner.

object

required

The metadata you sent. Reserved arukz. keys are never returned.

string

required

The token that unlocks this thread. Send it as X-ARUKZ-Visitor-Token on later requests. Shown only in this response.

// Runs on your website. The widget key is public and belongs in page source.
const MITHUNAI_API = `${MITHUNAI_URL}/arukz/api/v1`
const WIDGET_KEY = 'arukz_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e'

const response = await fetch(`${MITHUNAI_API}/widget/conversations`, {
  method: 'POST',
  headers: {
    'X-ARUKZ-Widget-Key': WIDGET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ metadata: { page: window.location.pathname } }),
})
const { conversation, visitor_token } = await response.json()

// Keep both for this thread. The token cannot be fetched again.
sessionStorage.setItem('mithunai.conversation', conversation.id)
sessionStorage.setItem('mithunai.visitorToken', visitor_token)

curl --request POST "$MITHUNAI_URL/arukz/api/v1/widget/conversations" \
  --header "X-ARUKZ-Widget-Key: arukz_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" \
  --header "Origin: https://docs.example.com" \
  --header "Content-Type: application/json" \
  --data '{"metadata": {"page": "/guides/rate-limits"}}'

{
  "conversation": {
    "id": "0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a",
    "assistant_id": "5b1e9c2a-7d4f-4e3b-9a61-0c8f2d7e4a13",
    "title": "New conversation",
    "status": "active",
    "turn_state": "idle",
    "message_count": 0,
    "created_at": "2026-09-24T10:02:17.559310+00:00",
    "updated_at": "2026-09-24T10:02:17.559310+00:00",
    "owner": { "type": "widget", "id": "8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" },
    "metadata": { "page": "/guides/rate-limits" }
  },
  "visitor_token": "5Ex151H7YDPzbzcCdGkgXUzttBDjF1q0OtEG5jfi-OM"
}

{ "code": "validation_error", "message": "That metadata key is reserved." }

{ "code": "authentication_error", "message": "Authentication is required." }

{ "code": "authorization_error", "message": "This widget may not be embedded from that origin." }

{ "code": "rate_limit_exceeded", "message": "Too many requests. Please retry later." }

Last modified on September 26, 2026

⌘I

// Runs on your website. The widget key is public and belongs in page source.
const MITHUNAI_API = `${MITHUNAI_URL}/arukz/api/v1`
const WIDGET_KEY = 'arukz_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e'

const response = await fetch(`${MITHUNAI_API}/widget/conversations`, {
  method: 'POST',
  headers: {
    'X-ARUKZ-Widget-Key': WIDGET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ metadata: { page: window.location.pathname } }),
})
const { conversation, visitor_token } = await response.json()

// Keep both for this thread. The token cannot be fetched again.
sessionStorage.setItem('mithunai.conversation', conversation.id)
sessionStorage.setItem('mithunai.visitorToken', visitor_token)

curl --request POST "$MITHUNAI_URL/arukz/api/v1/widget/conversations" \
  --header "X-ARUKZ-Widget-Key: arukz_wk_8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" \
  --header "Origin: https://docs.example.com" \
  --header "Content-Type: application/json" \
  --data '{"metadata": {"page": "/guides/rate-limits"}}'

{
  "conversation": {
    "id": "0e6a9b52-7d3f-4c18-a2e5-9b8c7d6e5f4a",
    "assistant_id": "5b1e9c2a-7d4f-4e3b-9a61-0c8f2d7e4a13",
    "title": "New conversation",
    "status": "active",
    "turn_state": "idle",
    "message_count": 0,
    "created_at": "2026-09-24T10:02:17.559310+00:00",
    "updated_at": "2026-09-24T10:02:17.559310+00:00",
    "owner": { "type": "widget", "id": "8d0f5a2e-3c41-4b7a-9e6d-1f2a3b4c5d6e" },
    "metadata": { "page": "/guides/rate-limits" }
  },
  "visitor_token": "5Ex151H7YDPzbzcCdGkgXUzttBDjF1q0OtEG5jfi-OM"
}

{ "code": "validation_error", "message": "That metadata key is reserved." }

{ "code": "authentication_error", "message": "Authentication is required." }

{ "code": "authorization_error", "message": "This widget may not be embedded from that origin." }

{ "code": "rate_limit_exceeded", "message": "Too many requests. Please retry later." }

Get started

Conversations

Assistants

Models

Knowledge

Widget deployments

Widget (public)

MCP

API keys

Members

Analytics

Support access

Branding

Operations

Start a widget thread for a visitor

Response

​Response

Response