Bases de Conhecimento

A API de Bases de Conhecimento permite consultar as bases da organização, gerenciar seus itens e recuperar contexto para aplicações externas. A API pública não cria, renomeia nem remove a base em si: essas operações são feitas no SquadOS. Pela API, você consulta bases existentes e cria, lê, atualiza ou remove itens.

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

Todas as requisições exigem Authorization: Bearer pk_.... Requisições com corpo também exigem Content-Type: application/json. Consulte Autenticação.

Todos os endpoints são limitados à organização do token. Um ID pertencente a outra organização é tratado como não encontrado.

Bases

GET /bases

Lista as bases da organização, da mais recente para a mais antiga.

Query	Tipo	Padrão	Regra
limit	integer	50	Máximo 100.
offset	integer	0	Posição inicial da página.

curl "https://api.squados.io/v1/bases?limit=50&offset=0" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

{
  "bases": [
    {
      "id": "BASE_ID",
      "name": "Documentação de Produto",
      "description": "Manuais e perguntas frequentes",
      "item_count": 42,
      "created_at": "2026-08-15T14:22:00Z",
      "updated_at": "2026-08-31T09:45:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

description pode ser null. item_count é a contagem atual de itens da base.

GET /bases/{baseId}

Retorna uma base e sua contagem de itens. description pode ser null.

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

Retorna 400 se baseId não for um UUID válido e 404 se a base não existir na organização.

Itens

Um item passa por processamento assíncrono. Os estados esperados são:

Status	Significado
pending	Aguardando processamento.
processing	Extração, divisão e indexação em andamento.
processed	Disponível para recuperação.
error	O processamento falhou.

GET /bases/{baseId}/items

Lista os itens da base, do mais recente para o mais antigo.

Query	Tipo	Padrão	Regra
limit	integer	50	Máximo 100.
offset	integer	0	Posição inicial da página.
status	string	—	Filtro exato: 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"

{
  "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 permite devoluções em até 30 dias...",
      "created_at": "2026-08-20T11:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

chunk_count, token_count e content_preview podem ser null enquanto não houver resultado de processamento.

POST /bases/{baseId}/items

Cria um item com source: "text".

Campo	Tipo	Obrigatório	Regra
name	string	Sim	Não pode ficar vazio após remover espaços das pontas.
content	string	Sim	Não pode ficar vazio; máximo de 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": "Aceitamos devoluções em até 30 dias após a compra."
  }'

A resposta 201 Created contém id, base_id, name, type, status e created_at. O item nasce com status: "pending" e segue de forma assíncrona para processing e processed ou error.

Nota

Depois de criar ou atualizar um item, consulte GET /bases/{baseId}/items/{itemId} até obter processed ou error. Não use apenas o tempo decorrido como sinal de conclusão.

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

Retorna os campos da listagem mais base_id e content.

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

Itens de texto preservam em content o conteúdo enviado, inclusive antes do fim da indexação. Para um item originado de arquivo, content pode ser null antes da extração. chunk_count, token_count e content_preview também podem ser null.

Retorna 400 se algum ID não for um UUID válido e 404 se a base ou o item não existir na organização.

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

Atualiza name, content ou ambos em um item com source: "text". Pelo menos um campo é obrigatório; content continua limitado a 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": "Aceitamos devoluções em até 45 dias após a compra."
  }'

Qualquer atualização — inclusive somente do nome — redefine status como pending e dispara novo processamento. A resposta 200 OK devolve o detalhe do item. Durante essa transição, chunk_count, token_count e content_preview podem ainda refletir o processamento anterior; trate esses campos como provisórios até o novo processed.

Cuidado

Itens com source: "file" não podem ser atualizados por este endpoint e retornam 409 Conflict. Um item que esteja em processing também retorna 409; espere o estado mudar antes de tentar novamente.

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

Remove o item e retorna 204 No Content, sem corpo. A exclusão enfileira, no mesmo commit, a limpeza assíncrona dos vetores e dos arquivos de chunks. O 204 confirma a remoção do item, não um prazo específico para concluir a limpeza interna.

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

Retorna 400 para IDs inválidos e 404 quando a base ou o item não existe na organização.

Recuperação híbrida (RAG)

POST /bases/{baseId}/query

Recupera trechos da base com o mesmo mecanismo usado pelos agentes: expansão de consulta, busca densa e lexical (BM25), fusão, reordenação e remoção de duplicatas. A consulta fica restrita à organização e à base informada.

Campo	Tipo	Obrigatório	Regra
query	string	Sim	Pergunta ou texto de busca; a string vazia é rejeitada.
limit	integer	Não	Padrão 5; normalizado para 1 a 20. Limita a apresentação, sem mudar a classificação do resultado.
min_score	number	Não	Obsoleto e ignorado. É aceito apenas por compatibilidade.

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 é o prazo para devolução?",
    "limit": 5
  }'

{
  "query": "Qual é o prazo para devolução?",
  "results": [
    {
      "content": "Aceitamos devoluções em até 45 dias após a compra.",
      "score": 0.92,
      "item_id": "ITEM_ID",
      "item_name": "Política de devolução",
      "chunk_index": 0
    }
  ],
  "total_results": 1,
  "embedding_model": "text-embedding-3-small",
  "outcome": "supported",
  "degraded": false
}

Como interpretar a resposta

Campo	Significado
results	Trechos finais, já reordenados e limitados. Em not_found, é sempre [].
total_results	Quantidade de trechos devolvidos em results.
outcome	supported, uncertain ou not_found. Use este campo para decidir se há contexto confiável.
degraded	true quando a organização usou o mecanismo legado de contingência. O formato da resposta permanece igual.
score	Relevância do reordenador entre 0 e 1, arredondada a quatro casas. Não é similaridade cosseno. Compare apenas resultados da mesma consulta e não adote um corte fixo.
item_name	Nome do item de origem; pode ser null.
chunk_index	Índice do trecho; pode ser inteiro, string ou null.

Cuidado

Não envie min_score para filtrar resultados: o campo é ignorado. Para automação segura, decida pelo outcome; um not_found já vem sem resultados.

O endpoint retorna 400 para IDs ou corpo inválidos, 404 para uma base inexistente, 503 service_unavailable quando uma dependência de recuperação está indisponível e 500 para configuração ausente ou falha inesperada.

Consulte Erros para o formato comum de falhas da API.