Start a conversation with an assistant

POST

conversations

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"}
  }'

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())

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())

{
  "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" }
}

{ "code": "validation_error", "message": "'assistant_id' is required." }

{ "code": "not_found", "message": "The requested resource was not found." }

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 or Stream a 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.

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.

string

A title for the conversation. 1 to 200 characters after trimming, on a single line: control characters and invisible formatting characters are rejected.

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.

Response

Returns 201 Created with the conversation.

string

required

The conversation ID.

string

required

The assistant that answers in this conversation.

string

required

The conversation title.

string

required

active or archived. A new conversation is active.

string

required

idle, or awaiting_answer while a question is being answered. A new conversation is idle.

integer

required

The number of messages in the conversation. Each question and each answer counts as one message.

string

required

When the conversation was created, as an ISO 8601 timestamp with a UTC offset.

string

required

When the conversation last changed, as an ISO 8601 timestamp with a UTC offset.

object

required

An opaque reference to the participant who owns the conversation.

Show properties

string

user for a signed-in person, service for an API key.

string

The owner’s identifier.

object

required

Your metadata entries. Empty object when you set none.

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"}
  }'

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())

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())

{
  "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" }
}

{ "code": "validation_error", "message": "'assistant_id' is required." }

{ "code": "not_found", "message": "The requested resource was not found." }

Last modified on September 26, 2026

⌘I

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"}
  }'

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())

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())

{
  "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" }
}

{ "code": "validation_error", "message": "'assistant_id' is required." }

{ "code": "not_found", "message": "The requested resource was not found." }

Get started

Conversations

Assistants

Models

Knowledge

Widget deployments

Widget (public)

MCP

API keys

Members

Analytics

Support access

Branding

Operations

Start a conversation with an assistant

Response

​Response

Response