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

# Assignação a Assistentes

> Controla quais assistentes enxergam cada conhecimento

Há duas formas de controlar quem enxerga um conhecimento:

1. **Escopo exclusivo** — o campo `assistant_id`, definido na
   [criação](/pt-BR/api-reference/knowledge/create) ou na
   [atualização](/pt-BR/api-reference/knowledge/update). Vincula o item a um
   único assistente.
2. **Exclusões** — para itens **globais**, uma lista de assistentes que *não*
   devem enxergar aquele conhecimento. É o que esta página cobre.

<Note>
  Use exclusões quando o material serve para quase todos os assistentes. Use
  `assistant_id` quando ele serve para um só.
</Note>

<Warning>
  Exclusões só valem para conhecimentos globais. Se o item já tem `assistant_id`
  preenchido, os endpoints abaixo retornam `409`. Torne-o global primeiro
  enviando `{"assistant_id": ""}` no
  [update](/pt-BR/api-reference/knowledge/update).
</Warning>

## Remover o acesso de um assistente

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

Adiciona o assistente à lista de exclusões. A operação é idempotente: repetir a
chamada não gera erro.

### Path Parameters

<ParamField path="id" type="string" required>
  UUID do conhecimento (precisa ser global)
</ParamField>

<ParamField path="assistantId" type="string" required>
  UUID do assistente que deixará de enxergar o conhecimento
</ParamField>

Retorna `200 OK` com o conhecimento atualizado.

<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 sua_chave_aqui"
  ```

  ```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 sua_chave_aqui' }
    }
  );

  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 sua_chave_aqui'}
  )

  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": "Política de trocas",
    "description": "Regras de troca e devolução",
    "content": "Trocas em até 30 dias mediante nota fiscal.",
    "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>

## Devolver o acesso a um assistente

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

Remove o assistente da lista de exclusões — ele volta a enxergar o conhecimento.

### Path Parameters

<ParamField path="id" type="string" required>
  UUID do conhecimento
</ParamField>

<ParamField path="assistantId" type="string" required>
  UUID do assistente que voltará a enxergar o conhecimento
</ParamField>

Retorna `200 OK` com o conhecimento atualizado.

<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 sua_chave_aqui"
  ```

  ```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 sua_chave_aqui' }
    }
  );
  ```
</RequestExample>

## Definir a lista completa de exclusões

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

Substitui toda a lista de uma vez. Útil para sincronizar a assignação a partir de
um sistema externo, sem precisar calcular o que entrou e o que saiu.

### Path Parameters

<ParamField path="id" type="string" required>
  UUID do conhecimento
</ParamField>

### Body

<ParamField body="assistant_ids" type="array" required>
  Lista de UUIDs dos assistentes que **não** devem enxergar o conhecimento.
  Envie `[]` para liberar o acesso a todos.
</ParamField>

Retorna `200 OK` com o conhecimento atualizado.

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.leavo.ai/backend/knowledge/9f1c2d34-5678-4abc-9def-0123456789ab/exclusions" \
    -H "Authorization: Bearer sua_chave_aqui" \
    -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 sua_chave_aqui',
        '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 sua_chave_aqui'},
      json={'assistant_ids': ['3f8a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8']}
  )

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

### Liberar para todos

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

## Erros

| Código | Descrição                                                                  |
| ------ | -------------------------------------------------------------------------- |
| `400`  | `assistant_ids` em formato inválido, ou UUID malformado                    |
| `401`  | Chave de API ausente ou inválida                                           |
| `404`  | Conhecimento não encontrado, ou assistente não pertence a esta organização |
| `409`  | O conhecimento não é global (já tem `assistant_id` preenchido)             |