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

# Criar Conhecimento

> Adiciona um conhecimento a partir de texto ou de um arquivo

Cria um item de conhecimento. Aceita dois formatos de envio: JSON (para conteúdo
em texto) ou `multipart/form-data` (para enviar um arquivo).

## Body

<ParamField body="name" type="string" required>
  Nome de exibição do conhecimento (1 a 255 caracteres)
</ParamField>

<ParamField body="content" type="string">
  Texto que será indexado. Opcional quando você envia um arquivo.
</ParamField>

<ParamField body="description" type="string">
  Descrição livre, até 1000 caracteres
</ParamField>

<ParamField body="usage_instruction" type="string">
  Orienta o assistente sobre quando usar este conhecimento (até 2000 caracteres)
</ParamField>

<ParamField body="assistant_id" type="string">
  UUID do assistente dono do conhecimento. Omita para criar um conhecimento
  **global**, visível a todos os assistentes.
</ParamField>

<Note>
  O `assistant_id` informado precisa ser de um assistente da sua própria
  organização. Caso contrário a requisição retorna `404`.
</Note>

## Response

Retorna `201 Created` com o conhecimento criado.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.leavo.ai/backend/knowledge" \
    -H "Authorization: Bearer sua_chave_aqui" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Política de trocas",
      "description": "Regras de troca e devolução",
      "content": "Trocas em até 30 dias mediante apresentação da nota fiscal.",
      "usage_instruction": "Use quando o lead perguntar sobre troca ou devolução."
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.leavo.ai/backend/knowledge', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sua_chave_aqui',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Política de trocas',
      description: 'Regras de troca e devolução',
      content: 'Trocas em até 30 dias mediante apresentação da nota fiscal.',
      usage_instruction: 'Use quando o lead perguntar sobre troca ou devolução.'
    })
  });

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

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

  response = requests.post(
      'https://api.leavo.ai/backend/knowledge',
      headers={'Authorization': 'Bearer sua_chave_aqui'},
      json={
          'name': 'Política de trocas',
          'description': 'Regras de troca e devolução',
          'content': 'Trocas em até 30 dias mediante apresentação da nota fiscal.',
          'usage_instruction': 'Use quando o lead perguntar sobre troca.'
      }
  )

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

<ResponseExample>
  ```json 201 Created 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 apresentação da nota fiscal.",
    "source_url": null,
    "usage_instruction": "Use quando o lead perguntar sobre troca ou devolução.",
    "assistant_id": null,
    "excluded_assistant_ids": [],
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
  ```
</ResponseExample>

## Criar a partir de um arquivo

Envie como `multipart/form-data` com o campo `file`. O texto é extraído do
arquivo e indexado automaticamente.

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

### Campos do Form

| Campo               | Tipo   | Obrigatório | Descrição                            |
| ------------------- | ------ | ----------- | ------------------------------------ |
| `name`              | string | Sim         | Nome de exibição                     |
| `file`              | file   | Não         | Arquivo a ser indexado (máx. 10 MB)  |
| `content`           | string | Não         | Texto adicional, se não usar arquivo |
| `description`       | string | Não         | Descrição livre                      |
| `usage_instruction` | string | Não         | Quando usar este conhecimento        |
| `assistant_id`      | string | Não         | Assistente dono; omita para global   |

### Extensões aceitas

`.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 sua_chave_aqui" \
    -F "name=Manual do produto" \
    -F "usage_instruction=Consulte para dúvidas técnicas sobre o produto." \
    -F "file=@manual_produto.pdf"
  ```

  ```javascript JavaScript theme={null}
  const formData = new FormData();
  formData.append('name', 'Manual do produto');
  formData.append('usage_instruction', 'Consulte para dúvidas técnicas.');
  formData.append('file', fileInput.files[0]);

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

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

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

  with open('manual_produto.pdf', 'rb') as f:
      response = requests.post(
          'https://api.leavo.ai/backend/knowledge',
          headers={'Authorization': 'Bearer sua_chave_aqui'},
          files={'file': f},
          data={'name': 'Manual do produto'}
      )

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

## Criar para um assistente específico

```bash cURL theme={null}
curl -X POST "https://api.leavo.ai/backend/knowledge" \
  -H "Authorization: Bearer sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Roteiro de qualificação",
    "content": "Pergunte o tamanho da equipe e o orçamento previsto.",
    "assistant_id": "3f8a1b2c-4d5e-6f70-8192-a3b4c5d6e7f8"
  }'
```

## Erros

| Código | Descrição                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------- |
| `400`  | `name` ausente, campo acima do limite de caracteres, extensão de arquivo não suportada ou arquivo acima de 10 MB |
| `401`  | Chave de API ausente ou inválida                                                                                 |
| `404`  | `assistant_id` não pertence a esta organização                                                                   |