Bases de Conhecimento

Esses endpoints permitem que você liste as bases de conhecimento da sua organização, gerencie os itens de texto de cada base e execute buscas semânticas (RAG) diretamente via API.

Base URL: https://api.squados.io/v1

Toda requisição exige o header Authorization: Bearer pk_.... Requisições com corpo precisam também de Content-Type: application/json. Consulte Autenticação para detalhes sobre como gerar e usar tokens.

---

Bases

GET /bases

Lista todas as bases de conhecimento da organização.

Parâmetros de query

Parâmetro	Tipo	Padrão	Descrição
limit	integer	50	Número de registros por página. Máximo: 100.
offset	integer	0	Posição inicial para paginação.

curl https://api.squados.io/v1/bases \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{
  "bases": [
    {
      "id": "BASE_ID",
      "name": "Documentação de Produto",
      "description": "Base com manuais e FAQs",
      "item_count": 42,
      "created_at": "2025-03-10T14:22:00Z",
      "updated_at": "2025-06-01T09:45:00Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

---

GET /bases/{baseId}

Retorna os detalhes de uma base de conhecimento específica.

Parâmetros de caminho

Parâmetro	Tipo	Descrição
baseId	uuid	ID da base de conhecimento.

curl https://api.squados.io/v1/bases/BASE_ID \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{
  "id": "BASE_ID",
  "name": "Documentação de Produto",
  "description": "Base com manuais e FAQs",
  "item_count": 42,
  "created_at": "2025-03-10T14:22:00Z",
  "updated_at": "2025-06-01T09:45:00Z"
}

Erros: 404 se a base não for encontrada.

---

Itens

GET /bases/{baseId}/items

Lista os itens de uma base de conhecimento com suporte a filtro por status.

Parâmetros de caminho

Parâmetro	Tipo	Descrição
baseId	uuid	ID da base de conhecimento.

Parâmetros de query

Parâmetro	Tipo	Padrão	Descrição
limit	integer	50	Número de registros por página. Máximo: 100.
offset	integer	0	Posição inicial para paginação.
status	string	—	Filtra por status: pending, processing, processed ou error.

curl "https://api.squados.io/v1/bases/BASE_ID/items?status=processed&limit=20" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{
  "base_id": "BASE_ID",
  "items": [
    {
      "id": "ITEM_ID",
      "name": "Política de Devolução",
      "type": "text",
      "source": "text",
      "status": "processed",
      "chunk_count": 4,
      "token_count": 812,
      "content_preview": "Nossa política de devolução permite a troca ou estorno de qualquer produto em até 30 dias…",
      "created_at": "2025-05-20T11:00:00Z"
    }
  ],
  "total": 18,
  "limit": 20,
  "offset": 0
}

---

POST /bases/{baseId}/items

Insere um novo item de texto na base de conhecimento.

Parâmetros de caminho

Parâmetro	Tipo	Descrição
baseId	uuid	ID da base de conhecimento.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Título do item. Mínimo: 1 caractere.
content	string	Sim	Conteúdo textual completo. Máximo: 100.000 caracteres.

curl -X POST https://api.squados.io/v1/bases/BASE_ID/items \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Política de Devolução",
    "content": "Nossa política permite a troca ou estorno de qualquer produto em até 30 dias após a compra..."
  }'

Resposta — 201 Created

{
  "id": "ITEM_ID",
  "base_id": "BASE_ID",
  "name": "Política de Devolução",
  "type": "text",
  "status": "pending",
  "created_at": "2025-06-08T12:00:00Z"
}

Nota

O processamento do item é assíncrono. Após a inserção, o item nasce com status: "pending" e passa por chunking, vetorização e indexação em background — etapas disparadas automaticamente por um trigger de banco. O fluxo completo é pending → processing → processed. Acompanhe o progresso fazendo GET /bases/{baseId}/items/{itemId} ou listando os itens com GET /bases/{baseId}/items.

Erros: 400 se o corpo for inválido ou o content ultrapassar 100.000 caracteres; 404 se a base não for encontrada.

---

GET /bases/{baseId}/items/{itemId}

Retorna o detalhe completo de um item, incluindo o conteúdo integral.

Parâmetros de caminho

Parâmetro	Tipo	Descrição
baseId	uuid	ID da base de conhecimento.
itemId	uuid	ID do item.

curl https://api.squados.io/v1/bases/BASE_ID/items/ITEM_ID \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{
  "id": "ITEM_ID",
  "base_id": "BASE_ID",
  "name": "Política de Devolução",
  "type": "text",
  "source": "text",
  "status": "processed",
  "chunk_count": 4,
  "token_count": 812,
  "content_preview": "Nossa política de devolução permite a troca ou estorno de qualquer produto em até 30 dias…",
  "content": "Nossa política de devolução permite a troca ou estorno de qualquer produto em até 30 dias após a compra. Para solicitar, acesse sua conta e abra um chamado...",
  "created_at": "2025-05-20T11:00:00Z"
}

O campo content contém o texto completo (até 100.000 caracteres). Se o item ainda não foi processado, content é null.

Erros: 400 se baseId ou itemId não forem UUIDs válidos; 404 se o item não for encontrado.

---

PATCH /bases/{baseId}/items/{itemId}

Atualiza o nome e/ou conteúdo de um item criado via texto (source: "text").

Parâmetros de caminho

Parâmetro	Tipo	Descrição
baseId	uuid	ID da base de conhecimento.
itemId	uuid	ID do item.

Corpo da requisição — ao menos um campo é obrigatório.

Campo	Tipo	Obrigatório	Descrição
name	string	Não	Novo título do item.
content	string	Não	Novo conteúdo textual. Máximo: 100.000 caracteres.

curl -X PATCH https://api.squados.io/v1/bases/BASE_ID/items/ITEM_ID \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Texto atualizado com as novas condições de devolução..."
  }'

Resposta — 200 OK

Retorna o BaseItemDetail atualizado. Note que status volta para "pending" porque o re-embedding é disparado automaticamente.

{
  "id": "ITEM_ID",
  "base_id": "BASE_ID",
  "name": "Política de Devolução",
  "type": "text",
  "source": "text",
  "status": "pending",
  "chunk_count": 0,
  "token_count": 0,
  "content_preview": null,
  "content": "Texto atualizado com as novas condições de devolução...",
  "created_at": "2025-05-20T11:00:00Z"
}

Cuidado

Itens com source: "file" (PDFs e outros arquivos enviados pelo painel) retornam 409 Conflict — você não pode editar o conteúdo deles via API. Para substituir o conteúdo, delete o item e crie um novo com source: "text". O endpoint também retorna 409 se o item estiver em status "processing" no momento da requisição.

---

DELETE /bases/{baseId}/items/{itemId}

Remove um item da base de conhecimento.

Parâmetros de caminho

Parâmetro	Tipo	Descrição
baseId	uuid	ID da base de conhecimento.
itemId	uuid	ID do item.

curl -X DELETE https://api.squados.io/v1/bases/BASE_ID/items/ITEM_ID \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 204 No Content

Sem corpo. A limpeza dos vetores correspondentes no banco vetorial (Qdrant) é enfileirada automaticamente após a remoção.

Erros: 404 se o item não for encontrado.

---

Busca semântica (RAG)

POST /bases/{baseId}/query

Executa uma busca semântica diretamente na base usando embeddings. Útil para integrar RAG em sistemas externos — receba os chunks mais relevantes para uma pergunta e use-os no seu próprio pipeline.

Parâmetros de caminho

Parâmetro	Tipo	Descrição
baseId	uuid	ID da base de conhecimento.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
query	string	Sim	Texto a ser buscado semanticamente.
limit	integer	Não	Número máximo de resultados. Padrão: 5. Máximo: 20.
min_score	number	Não	Score mínimo de similaridade (0 a 1). Padrão: 0.6.

Exemplo simples:

curl -X POST https://api.squados.io/v1/bases/BASE_ID/query \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Qual é a política de devolução?"
  }'

Exemplo com filtros:

curl -X POST https://api.squados.io/v1/bases/BASE_ID/query \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Quais são os preços dos produtos?",
    "limit": 10,
    "min_score": 0.7
  }'

Resposta — 200 OK

{
  "query": "Qual é a política de devolução?",
  "results": [
    {
      "content": "Nossa política permite a troca ou estorno de qualquer produto em até 30 dias após a compra...",
      "score": 0.92,
      "item_id": "ITEM_ID",
      "item_name": "Política de Devolução",
      "chunk_index": 0
    },
    {
      "content": "Para produtos com defeito de fabricação, o prazo é estendido para 90 dias conforme o CDC...",
      "score": 0.81,
      "item_id": "ITEM_ID",
      "item_name": "Política de Devolução",
      "chunk_index": 1
    }
  ],
  "total_results": 2,
  "embedding_model": "text-embedding-3-small"
}

Cada resultado retorna o chunk de texto (content), seu score de similaridade (0 a 1), o item de origem e o índice do chunk dentro do item.

Erros: 400 se query for inválida ou ausente; 404 se a base não for encontrada; 500 se o RAG não estiver configurado para a base.

---

Para detalhes sobre erros e códigos de status HTTP, consulte Erros.