> ## 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 a knowledge collection to ingest into

> Create the corpus your sources ingest into and your assistants answer from. The embedding model and vector width are fixed at creation and can never be changed.

A collection belongs to your organization. Collection names are unique within an organization, so creating a second collection with a name you already use returns `409`.

The embedding model and vector width are fixed when the collection is created and can never be changed afterwards, because vectors from two models cannot be compared. Omit both fields to use your deployment's default embedding. Two collections with different embeddings cannot be combined behind one assistant.

Creating a collection requires a role that can manage knowledge. A read-only member receives `403`. See [Organizations and roles](/concepts/organizations-and-roles).

<ParamField body="name" type="string" required>
  Display name, at most 200 characters. Leading and trailing whitespace is trimmed, and a name that
  is empty after trimming is refused.
</ParamField>

<ParamField body="description" type="string" default="">
  Free-text description. Requests over 4,000 characters are refused. The stored value is trimmed and
  truncated to 1,000 characters.
</ParamField>

<ParamField body="embedding_model" type="string">
  Embedding model for this collection. Omit it, or send an empty string, to use the deployment's
  default.
</ParamField>

<ParamField body="embedding_dimensions" type="integer">
  Vector width the embedding model produces. A positive integer, at most 100,000. Omit it to use the
  deployment's default.
</ParamField>

## Response

Returns `201` with the new collection.

<ResponseField name="id" type="string" required>
  Collection ID (a UUID). Pass it as `collection_id` to other knowledge endpoints and to an
  assistant's `knowledge_base_ids`.
</ResponseField>

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

<ResponseField name="description" type="string" required>
  The stored description. Empty string when none was given.
</ResponseField>

<ResponseField name="status" type="string" required>
  `active` for a new collection. See [Update a
  collection](/api-reference/knowledge/update-collection) for `archived`.
</ResponseField>

<ResponseField name="embedding_model" type="string" required>
  The embedding model the collection was created with.
</ResponseField>

<ResponseField name="embedding_dimensions" type="integer" required>
  The vector width the collection was created with.
</ResponseField>

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

<ResponseField name="updated_at" type="string" required>
  When the collection 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/knowledge/collections" \
    --header "Authorization: Bearer $MITHUNAI_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{"name": "Product documentation", "description": "Public docs and API reference"}'
  ```

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

  response = requests.post(
      f"{os.environ['MITHUNAI_URL']}/arukz/api/v1/knowledge/collections",
      headers={"Authorization": f"Bearer {os.environ['MITHUNAI_API_KEY']}"},
      json={"name": "Product documentation", "description": "Public docs and API reference"},
      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/knowledge/collections`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.MITHUNAI_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Product documentation',
      description: 'Public docs and API reference',
    }),
  })
  console.log(await response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "0b6f2c14-8a3d-4e91-9c77-2f5b1d0a4e88",
    "name": "Product documentation",
    "description": "Public docs and API reference",
    "status": "active",
    "embedding_model": "text-embedding-3-small",
    "embedding_dimensions": 1536,
    "created_at": "2026-09-24T10:15:02.418331",
    "updated_at": "2026-09-24T10:15:02.418331"
  }
  ```

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

  ```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": "A knowledge collection with that name already exists." }
  ```
</ResponseExample>