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

# Visão Geral

> Como a base de conhecimento alimenta as respostas dos seus assistentes

A base de conhecimento é o material que seus assistentes consultam para responder
seus leads: políticas, tabelas de preço, manuais, perguntas frequentes. Cada item
pode ser criado a partir de um texto ou de um arquivo enviado.

## Escopo: global ou de um assistente

Todo item de conhecimento tem um escopo, definido pelo campo `assistant_id`:

| `assistant_id`        | Escopo    | Quem enxerga                   |
| --------------------- | --------- | ------------------------------ |
| ausente ou `null`     | Global    | Todos os assistentes do tenant |
| UUID de um assistente | Exclusivo | Apenas aquele assistente       |

<Note>
  Um item exclusivo pertence a um único assistente. Para compartilhar o mesmo
  material entre alguns assistentes — mas não todos — deixe o item global e use
  as [exclusões](/pt-BR/api-reference/knowledge/assignments).
</Note>

## Exclusões: recortando um item global

Itens globais aceitam uma lista `excluded_assistant_ids`. Os assistentes nessa
lista deixam de enxergar aquele conhecimento, mesmo ele sendo global.

```
Item global "Tabela de preços"
  excluded_assistant_ids: ["assistente-suporte"]

  → Assistente de Vendas  ✅ enxerga
  → Assistente de Suporte ❌ não enxerga
```

<Warning>
  Exclusões só se aplicam a itens **globais**. Tentar excluir um assistente de um
  item que já tem `assistant_id` preenchido retorna `409`.
</Warning>

## Formatos de arquivo aceitos

| Categoria | Extensões                              |
| --------- | -------------------------------------- |
| Texto     | `.txt`, `.md`, `.mdx`, `.rst`, `.adoc` |
| Documento | `.pdf`, `.html`                        |
| Planilha  | `.xlsx`, `.xls`, `.csv`                |

O limite é de **10 MB** por arquivo. O conteúdo é extraído como texto e indexado —
imagens dentro do arquivo não são interpretadas.

## Instrução de uso

O campo opcional `usage_instruction` (até 2000 caracteres) orienta o assistente
sobre **quando** recorrer àquele conhecimento. É útil quando você tem vários itens
parecidos:

```json theme={null}
{
  "name": "Tabela de preços 2026",
  "usage_instruction": "Use apenas quando o lead perguntar valores. Nunca cite preços de anos anteriores."
}
```

## Objeto de conhecimento

```json 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": "Use quando o lead perguntar sobre troca ou devolução.",
  "assistant_id": null,
  "excluded_assistant_ids": ["3f8a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8"],
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-02-02T09:12:00Z"
}
```

| Campo                    | Tipo           | Descrição                                      |
| ------------------------ | -------------- | ---------------------------------------------- |
| `id`                     | UUID           | Identificador do conhecimento                  |
| `tenant_id`              | UUID           | Organização dona do item                       |
| `name`                   | string         | Nome de exibição (1–255 caracteres)            |
| `description`            | string         | Descrição livre (até 1000 caracteres)          |
| `content`                | string         | Texto indexado                                 |
| `source_url`             | string \| null | Preenchido quando o item veio de uma URL       |
| `usage_instruction`      | string \| null | Quando usar este conhecimento (até 2000)       |
| `assistant_id`           | UUID \| null   | `null` = global                                |
| `excluded_assistant_ids` | array          | Assistentes sem acesso (só para itens globais) |

## Endpoints

| Método   | Rota                                               | Descrição                                                             |
| -------- | -------------------------------------------------- | --------------------------------------------------------------------- |
| `GET`    | `/backend/knowledge`                               | [Listar](/pt-BR/api-reference/knowledge/list)                         |
| `GET`    | `/backend/knowledge/{id}`                          | [Obter](/pt-BR/api-reference/knowledge/list)                          |
| `POST`   | `/backend/knowledge`                               | [Criar](/pt-BR/api-reference/knowledge/create)                        |
| `PUT`    | `/backend/knowledge/{id}`                          | [Atualizar](/pt-BR/api-reference/knowledge/update)                    |
| `DELETE` | `/backend/knowledge/{id}`                          | [Excluir](/pt-BR/api-reference/knowledge/delete)                      |
| `PUT`    | `/backend/knowledge/{id}/exclusions`               | [Definir exclusões](/pt-BR/api-reference/knowledge/assignments)       |
| `POST`   | `/backend/knowledge/{id}/exclusions/{assistantId}` | [Excluir um assistente](/pt-BR/api-reference/knowledge/assignments)   |
| `DELETE` | `/backend/knowledge/{id}/exclusions/{assistantId}` | [Restaurar um assistente](/pt-BR/api-reference/knowledge/assignments) |

<Note>
  Todos os endpoints operam apenas sobre o conhecimento da organização dona da
  chave de API usada na requisição. Não é possível ler ou alterar dados de outra
  organização.
</Note>