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

# Assistant Assignment

> Control which assistants can see each knowledge item

There are two ways to control who sees a knowledge item:

1. **Exclusive scope** — the `assistant_id` field, set on
   [creation](/en/api-reference/knowledge/create) or on
   [update](/en/api-reference/knowledge/update). It links the item to a single
   assistant.
2. **Exclusions** — for **global** items, a list of assistants that should *not*
   see that knowledge item. That is what this page covers.

<Note>
  Use exclusions when the material is meant for almost every assistant. Use
  `assistant_id` when it is meant for a single one.
</Note>

<Warning>
  Exclusions only apply to global knowledge items. If the item already has
  `assistant_id` filled in, the endpoints below return `409`. Make it global
  first by sending `{"assistant_id": ""}` on
  [update](/en/api-reference/knowledge/update).
</Warning>

## Remove an assistant's access

```bash theme={null}
POST /backend/knowledge/{id}/exclusions/{assistantId}
```

Adds the assistant to the exclusion list. The operation is idempotent: repeating
the call does not raise an error.

### Path Parameters

<ParamField path="id" type="string" required>
  Knowledge item UUID (it must be global)
</ParamField>

<ParamField path="assistantId" type="string" required>
  UUID of the assistant that will stop seeing the knowledge item
</ParamField>

Returns `200 OK` with the updated knowledge item.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.leavo.ai/backend/knowledge/9f1c2d34-5678-4abc-9def-0123456789ab/exclusions/3f8a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8" \
    -H "Authorization: Bearer your_api_key_here"
  ```

  ```javascript JavaScript theme={null}
  const knowledgeId = '9f1c2d34-5678-4abc-9def-0123456789ab';
  const assistantId = '3f8a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8';

  const response = await fetch(
    `https://api.leavo.ai/backend/knowledge/${knowledgeId}/exclusions/${assistantId}`,
    {
      method: 'POST',
      headers: { 'Authorization': 'Bearer your_api_key_here' }
    }
  );

  console.log((await response.json()).excluded_assistant_ids);
  ```

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

  knowledge_id = '9f1c2d34-5678-4abc-9def-0123456789ab'
  assistant_id = '3f8a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8'

  response = requests.post(
      f'https://api.leavo.ai/backend/knowledge/{knowledge_id}/exclusions/{assistant_id}',
      headers={'Authorization': 'Bearer your_api_key_here'}
  )

  print(response.json()['excluded_assistant_ids'])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK 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 with the receipt.",
    "source_url": null,
    "usage_instruction": null,
    "assistant_id": null,
    "excluded_assistant_ids": ["3f8a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8"],
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-11T11:20:00Z"
  }
  ```
</ResponseExample>

## Give an assistant its access back

```bash theme={null}
DELETE /backend/knowledge/{id}/exclusions/{assistantId}
```

Removes the assistant from the exclusion list — it can see the knowledge item
again.

### Path Parameters

<ParamField path="id" type="string" required>
  Knowledge item UUID
</ParamField>

<ParamField path="assistantId" type="string" required>
  UUID of the assistant that will see the knowledge item again
</ParamField>

Returns `200 OK` with the updated knowledge item.

<RequestExample>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.leavo.ai/backend/knowledge/9f1c2d34-5678-4abc-9def-0123456789ab/exclusions/3f8a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8" \
    -H "Authorization: Bearer your_api_key_here"
  ```

  ```javascript JavaScript theme={null}
  const knowledgeId = '9f1c2d34-5678-4abc-9def-0123456789ab';
  const assistantId = '3f8a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8';

  await fetch(
    `https://api.leavo.ai/backend/knowledge/${knowledgeId}/exclusions/${assistantId}`,
    {
      method: 'DELETE',
      headers: { 'Authorization': 'Bearer your_api_key_here' }
    }
  );
  ```
</RequestExample>

## Set the full exclusion list

```bash theme={null}
PUT /backend/knowledge/{id}/exclusions
```

Replaces the whole list at once. Useful to sync the assignment from an external
system, without having to compute what was added and what was removed.

### Path Parameters

<ParamField path="id" type="string" required>
  Knowledge item UUID
</ParamField>

### Body

<ParamField body="assistant_ids" type="array" required>
  List of UUIDs of the assistants that must **not** see the knowledge item.
  Send `[]` to grant access to everyone.
</ParamField>

Returns `200 OK` with the updated knowledge item.

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.leavo.ai/backend/knowledge/9f1c2d34-5678-4abc-9def-0123456789ab/exclusions" \
    -H "Authorization: Bearer your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "assistant_ids": [
        "3f8a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8",
        "7c6d5e4f-3a2b-4c1d-9e8f-0a1b2c3d4e5f"
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const knowledgeId = '9f1c2d34-5678-4abc-9def-0123456789ab';

  const response = await fetch(
    `https://api.leavo.ai/backend/knowledge/${knowledgeId}/exclusions`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        assistant_ids: [
          '3f8a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8',
          '7c6d5e4f-3a2b-4c1d-9e8f-0a1b2c3d4e5f'
        ]
      })
    }
  );

  console.log((await response.json()).excluded_assistant_ids);
  ```

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

  knowledge_id = '9f1c2d34-5678-4abc-9def-0123456789ab'

  response = requests.put(
      f'https://api.leavo.ai/backend/knowledge/{knowledge_id}/exclusions',
      headers={'Authorization': 'Bearer your_api_key_here'},
      json={'assistant_ids': ['3f8a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8']}
  )

  print(response.json()['excluded_assistant_ids'])
  ```
</RequestExample>

### Grant access to everyone

```bash cURL theme={null}
curl -X PUT "https://api.leavo.ai/backend/knowledge/9f1c2d34-5678-4abc-9def-0123456789ab/exclusions" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"assistant_ids": []}'
```

## Errors

| Code  | Description                                                                 |
| ----- | --------------------------------------------------------------------------- |
| `400` | `assistant_ids` in an invalid format, or malformed UUID                     |
| `401` | Missing or invalid API key                                                  |
| `404` | Knowledge item not found, or assistant does not belong to this organization |
| `409` | The knowledge item is not global (it already has `assistant_id` filled in)  |