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

# Create Knowledge

> Add a knowledge item from text or from a file

Creates a knowledge item. Two request formats are accepted: JSON (for text
content) or `multipart/form-data` (to upload a file).

## Body

<ParamField body="name" type="string" required>
  Display name of the knowledge item (1 to 255 characters)
</ParamField>

<ParamField body="content" type="string">
  Text that will be indexed. Optional when you upload a file.
</ParamField>

<ParamField body="description" type="string">
  Free-form description, up to 1000 characters
</ParamField>

<ParamField body="usage_instruction" type="string">
  Tells the assistant when to use this knowledge (up to 2000 characters)
</ParamField>

<ParamField body="assistant_id" type="string">
  UUID of the assistant that owns the knowledge item. Omit it to create a
  **global** knowledge item, visible to every assistant.
</ParamField>

<Note>
  The `assistant_id` you provide must belong to an assistant in your own
  organization. Otherwise the request returns `404`.
</Note>

## Response

Returns `201 Created` with the created knowledge item.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.leavo.ai/backend/knowledge" \
    -H "Authorization: Bearer your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Return policy",
      "description": "Exchange and return rules",
      "content": "Returns within 30 days upon presentation of the receipt.",
      "usage_instruction": "Use when the lead asks about exchanges or returns."
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.leavo.ai/backend/knowledge', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Return policy',
      description: 'Exchange and return rules',
      content: 'Returns within 30 days upon presentation of the receipt.',
      usage_instruction: 'Use when the lead asks about exchanges or returns.'
    })
  });

  const knowledge = await response.json();
  console.log('Created:', knowledge.id);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.leavo.ai/backend/knowledge',
      headers={'Authorization': 'Bearer your_api_key_here'},
      json={
          'name': 'Return policy',
          'description': 'Exchange and return rules',
          'content': 'Returns within 30 days upon presentation of the receipt.',
          'usage_instruction': 'Use when the lead asks about exchanges.'
      }
  )

  print('Created:', response.json()['id'])
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "9f1c2d34-5678-4abc-9def-0123456789ab",
    "tenant_id": "d6b10acc-2307-413f-a4de-4c2edf3f9a70",
    "name": "Return policy",
    "description": "Exchange and return rules",
    "content": "Returns within 30 days upon presentation of the receipt.",
    "source_url": null,
    "usage_instruction": "Use when the lead asks about exchanges or returns.",
    "assistant_id": null,
    "excluded_assistant_ids": [],
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
  ```
</ResponseExample>

## Create from a file

Send the request as `multipart/form-data` with the `file` field. The text is
extracted from the file and indexed automatically.

```bash theme={null}
POST /backend/knowledge
Content-Type: multipart/form-data
```

### Form Fields

| Field               | Type   | Required | Description                                  |
| ------------------- | ------ | -------- | -------------------------------------------- |
| `name`              | string | Yes      | Display name                                 |
| `file`              | file   | No       | File to be indexed (max 10 MB)               |
| `content`           | string | No       | Additional text, if you are not using a file |
| `description`       | string | No       | Free-form description                        |
| `usage_instruction` | string | No       | When to use this knowledge item              |
| `assistant_id`      | string | No       | Owning assistant; omit for global            |

### Accepted extensions

`.txt` · `.md` · `.mdx` · `.rst` · `.adoc` · `.html` · `.pdf` · `.xlsx` · `.xls` · `.csv`

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.leavo.ai/backend/knowledge" \
    -H "Authorization: Bearer your_api_key_here" \
    -F "name=Product manual" \
    -F "usage_instruction=Check this for technical questions about the product." \
    -F "file=@product_manual.pdf"
  ```

  ```javascript JavaScript theme={null}
  const formData = new FormData();
  formData.append('name', 'Product manual');
  formData.append('usage_instruction', 'Check this for technical questions.');
  formData.append('file', fileInput.files[0]);

  const response = await fetch('https://api.leavo.ai/backend/knowledge', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key_here'
    },
    body: formData
  });

  console.log('Created:', (await response.json()).id);
  ```

  ```python Python theme={null}
  import requests

  with open('product_manual.pdf', 'rb') as f:
      response = requests.post(
          'https://api.leavo.ai/backend/knowledge',
          headers={'Authorization': 'Bearer your_api_key_here'},
          files={'file': f},
          data={'name': 'Product manual'}
      )

  print('Created:', response.json()['id'])
  ```
</RequestExample>

## Create for a specific assistant

```bash cURL theme={null}
curl -X POST "https://api.leavo.ai/backend/knowledge" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Qualification script",
    "content": "Ask about the team size and the expected budget.",
    "assistant_id": "3f8a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8"
  }'
```

## Errors

| Code  | Description                                                                                      |
| ----- | ------------------------------------------------------------------------------------------------ |
| `400` | Missing `name`, a field over the character limit, unsupported file extension, or file over 10 MB |
| `401` | Missing or invalid API key                                                                       |
| `404` | `assistant_id` does not belong to this organization                                              |