> ## 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 conversation with an assistant

> Create an empty conversation bound to one assistant for life. The caller that creates it owns it, and only the owner may ask questions in it or rename it.

A conversation is created empty and bound to one assistant for its whole life: you cannot move it to a different assistant later. Ask the first question with [Send a message](/api-reference/conversations/send-message) or [Stream a message](/api-reference/conversations/stream-message).

The caller who creates a conversation owns it. Only the owner can ask questions in it or rename it, so a conversation created with an API key belongs to that key, not to the person who minted it. Your key's role needs permission to read assistants and to create conversations; the `normal` role has both.

If you omit `title`, the conversation is called `New conversation` until its first question, and then takes the first line of that question (up to 80 characters) as its title.

<ParamField body="assistant_id" type="string" required>
  The ID of an assistant in your organization. An assistant that does not exist in your organization
  returns `404`. An assistant that cannot currently answer (for example, one that is disabled or has
  no knowledge attached) returns `400`.
</ParamField>

<ParamField body="title" type="string">
  A title for the conversation. 1 to 200 characters after trimming, on a single line: control
  characters and invisible formatting characters are rejected.
</ParamField>

<ParamField body="metadata" type="object">
  Your own labels for the conversation, as string keys and string values. At most 20 entries. Keys
  are 1 to 64 characters, start with a lowercase letter and use only `a-z`, `0-9`, `.`, `_` and `-`.
  Values are up to 512 characters on a single line. Keys beginning with `arukz.` are reserved and
  are never returned. Do not put credentials or secrets here: metadata is returned verbatim.
</ParamField>

## Response

Returns `201 Created` with the conversation.

<ResponseField name="id" type="string" required>
  The conversation ID.
</ResponseField>

<ResponseField name="assistant_id" type="string" required>
  The assistant that answers in this conversation.
</ResponseField>

<ResponseField name="title" type="string" required>
  The conversation title.
</ResponseField>

<ResponseField name="status" type="string" required>
  `active` or `archived`. A new conversation is `active`.
</ResponseField>

<ResponseField name="turn_state" type="string" required>
  `idle`, or `awaiting_answer` while a question is being answered. A new conversation is `idle`.
</ResponseField>

<ResponseField name="message_count" type="integer" required>
  The number of messages in the conversation. Each question and each answer counts as one message.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  When the conversation was created, as an ISO 8601 timestamp with a UTC offset.
</ResponseField>

<ResponseField name="updated_at" type="string" required>
  When the conversation last changed, as an ISO 8601 timestamp with a UTC offset.
</ResponseField>

<ResponseField name="owner" type="object" required>
  An opaque reference to the participant who owns the conversation.

  <Expandable title="properties">
    <ResponseField name="type" type="string">
      `user` for a signed-in person, `service` for an API key.
    </ResponseField>

    <ResponseField name="id" type="string">
      The owner's identifier.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object" required>
  Your metadata entries. Empty object when you set none.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST "$MITHUNAI_URL/arukz/api/v1/conversations" \
    --header "Authorization: Bearer $MITHUNAI_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "assistant_id": "5b0e2c7a-91d4-4f3e-8a6b-2d7c9e1f4a38",
      "metadata": {"source": "support-portal"}
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os, requests

  response = requests.post(
      f"{os.environ['MITHUNAI_URL']}/arukz/api/v1/conversations",
      headers={"Authorization": f"Bearer {os.environ['MITHUNAI_API_KEY']}"},
      json={
          "assistant_id": "5b0e2c7a-91d4-4f3e-8a6b-2d7c9e1f4a38",
          "metadata": {"source": "support-portal"},
      },
      timeout=60,
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(`${process.env.MITHUNAI_URL}/arukz/api/v1/conversations`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.MITHUNAI_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      assistant_id: '5b0e2c7a-91d4-4f3e-8a6b-2d7c9e1f4a38',
      metadata: { source: 'support-portal' },
    }),
  })
  console.log(await response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "c41f8a2e-6d93-4b0a-b7e5-3f1d2c8a9e60",
    "assistant_id": "5b0e2c7a-91d4-4f3e-8a6b-2d7c9e1f4a38",
    "title": "New conversation",
    "status": "active",
    "turn_state": "idle",
    "message_count": 0,
    "created_at": "2026-09-24T10:15:02.184311+00:00",
    "updated_at": "2026-09-24T10:15:02.184311+00:00",
    "owner": { "type": "service", "id": "9a7d3e51-2f6c-4b88-a0d4-6e1b5c3f7a92" },
    "metadata": { "source": "support-portal" }
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "validation_error", "message": "'assistant_id' is required." }
  ```

  ```json 404 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "not_found", "message": "The requested resource was not found." }
  ```
</ResponseExample>