> ## 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.

# Create an assistant over your knowledge

> Create an assistant in your own organisation, pointed at the collections it answers from. The server assigns the id, and a new assistant starts out active.

The assistant is created in the organization your credential belongs to. You cannot name another organization, and you cannot choose the assistant's `id`: the server assigns it. A new assistant always starts with `status` set to `active`.

Every knowledge base you list must exist in your organization, or the request fails with `400`. Assistant names are unique within an organization; a name that is already taken returns `409`.

An assistant can answer questions only when it is `active` **and** has at least one knowledge base. The `answerable` field in the response tells you whether that is true. See [Configure an assistant](/assistants/configure).

Creating an assistant requires the owner, admin or editor role. See [Organizations and roles](/concepts/organizations-and-roles).

<ParamField body="name" type="string" required>
  Display name. Leading and trailing whitespace is trimmed; the result must be 1 to 120 characters
  on a single line, with no control, invisible formatting or line-separator characters.
</ParamField>

<ParamField body="knowledge_base_ids" type="string[]" default="[]">
  IDs (UUIDs) of the knowledge bases this assistant answers from. At most 20 after duplicates are
  removed; order is kept. An assistant with none is created but is not `answerable`.
</ParamField>

<ParamField body="model" type="string" default="anthropic/claude-sonnet-5">
  Model selector, either `provider/model` or a bare model name. The provider must be one the
  platform supports, and a bare model name must match exactly one model in the platform's catalogue,
  or the request fails with `400`. `GET /models` lists what your deployment offers.
</ParamField>

<ParamField body="instruction" type="string">
  Guidance added to the assistant's answer policy. Before it is stored, control and invisible
  formatting characters are removed, runs of blank lines are collapsed, and surrounding whitespace
  is trimmed. Text longer than 8,000 characters is not refused: it is cut and ends with `   […truncated]`. An empty or whitespace-only value is stored as `null`.
</ParamField>

<ParamField body="description" type="string" default="&#x22;&#x22;">
  Description for administrators, up to 500 characters on a single line. It is never sent to the
  model.
</ParamField>

## Response

Returns `201 Created` with the full assistant.

<ResponseField name="id" type="string" required>
  The assistant's ID (UUID).
</ResponseField>

<ResponseField name="name" type="string" required>
  Display name.
</ResponseField>

<ResponseField name="description" type="string" required>
  Description. Empty string when none was set.
</ResponseField>

<ResponseField name="status" type="string" required>
  Lifecycle status: `active`, `disabled` or `archived`. Always `active` on creation.
</ResponseField>

<ResponseField name="model" type="string" required>
  The model selector.
</ResponseField>

<ResponseField name="knowledge_base_ids" type="string[]" required>
  Knowledge bases the assistant answers from, in the order you gave.
</ResponseField>

<ResponseField name="instruction" type="string | null" required>
  The stored instruction, or `null` when there is none.
</ResponseField>

<ResponseField name="answerable" type="boolean" required>
  `true` when the assistant is `active` and has at least one knowledge base.
</ResponseField>

<ResponseField name="revision" type="integer" required>
  Concurrency revision. Starts at `1`. Send it back on `PATCH /assistants/{assistant_id}`.
</ResponseField>

<ResponseField name="created_at" type="string | null" required>
  When the assistant was created, ISO 8601 in UTC.
</ResponseField>

<ResponseField name="updated_at" type="string | null" required>
  When the assistant was last changed, ISO 8601 in UTC.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request POST "$MITHUNAI_URL/arukz/api/v1/assistants" \
    --header "Authorization: Bearer $MITHUNAI_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "Developer docs assistant",
      "knowledge_base_ids": ["a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21"],
      "instruction": "Answer for developers integrating the public API. Prefer code samples.",
      "description": "Answers questions on the developer 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/assistants",
      headers={"Authorization": f"Bearer {os.environ['MITHUNAI_API_KEY']}"},
      json={
          "name": "Developer docs assistant",
          "knowledge_base_ids": ["a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21"],
          "instruction": "Answer for developers integrating the public API. Prefer code samples.",
          "description": "Answers questions on the developer 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/assistants`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.MITHUNAI_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Developer docs assistant',
      knowledge_base_ids: ['a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21'],
      instruction: 'Answer for developers integrating the public API. Prefer code samples.',
      description: 'Answers questions on the developer portal',
    }),
  })
  console.log(await response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "5b1e9c2a-7d4f-4e3b-9a61-0c8f2d7e4a13",
    "name": "Developer docs assistant",
    "description": "Answers questions on the developer portal",
    "status": "active",
    "model": "anthropic/claude-sonnet-5",
    "knowledge_base_ids": ["a3c7e1f0-2b9d-4c56-8e14-7f0a9b3d6e21"],
    "instruction": "Answer for developers integrating the public API. Prefer code samples.",
    "answerable": true,
    "revision": 1,
    "created_at": "2026-09-20T14:03:11.482190+00:00",
    "updated_at": "2026-09-20T14:03:11.482190+00:00"
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "code": "validation_error",
    "message": "A knowledge base named by this assistant does not exist."
  }
  ```

  ```json 403 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "authorization_error", "message": "You do not have permission to perform this action." }
  ```

  ```json 409 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "conflict", "message": "An assistant with that name already exists." }
  ```
</ResponseExample>