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

# Start a widget thread for a visitor

> Open a conversation thread for one anonymous visitor and receive the visitor token that unlocks it. Takes the public widget key and allowed Origin, no API key.

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](/channels/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](/api-reference/widget/send-thread-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.

<ParamField header="X-ARUKZ-Widget-Key" type="string" required>
  The deployment's public widget key, `arukz_wk_…`.
</ParamField>

<ParamField header="Origin" type="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.
</ParamField>

<ParamField body="title" type="string">
  A title for the thread, up to 200 characters. When omitted, the thread is titled `New
      conversation` until the first question renames it.
</ParamField>

<ParamField body="metadata" type="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.
</ParamField>

## Response

Returns `201 Created`.

<ResponseField name="conversation" type="object" required>
  The new conversation.

  <Expandable title="properties">
    <ResponseField name="id" type="string" required>The conversation's ID (UUID).</ResponseField>
    <ResponseField name="assistant_id" type="string" required>The assistant the deployment embeds.</ResponseField>
    <ResponseField name="title" type="string" required>The title you sent, or `New conversation`.</ResponseField>
    <ResponseField name="status" type="string" required>`active`.</ResponseField>
    <ResponseField name="turn_state" type="string" required>`idle`: ready for a question.</ResponseField>
    <ResponseField name="message_count" type="integer" required>`0`.</ResponseField>
    <ResponseField name="created_at" type="string" required>ISO 8601 in UTC.</ResponseField>
    <ResponseField name="updated_at" type="string" required>ISO 8601 in UTC.</ResponseField>
    <ResponseField name="owner" type="object" required>`{"type": "widget", "id": <deployment ID>}`. All threads of one embed share this owner.</ResponseField>
    <ResponseField name="metadata" type="object" required>The metadata you sent. Reserved `arukz.` keys are never returned.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="visitor_token" type="string" required>
  The token that unlocks this thread. Send it as `X-ARUKZ-Visitor-Token` on later requests. Shown
  only in this response.
</ResponseField>

<RequestExample>
  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // 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)
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"}}'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "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"
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "validation_error", "message": "That metadata key is reserved." }
  ```

  ```json 401 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "authentication_error", "message": "Authentication is required." }
  ```

  ```json 403 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "authorization_error", "message": "This widget may not be embedded from that origin." }
  ```

  ```json 429 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "rate_limit_exceeded", "message": "Too many requests. Please retry later." }
  ```
</ResponseExample>