IPBX Quantum
PORTAL DO DESENVOLVEDOR

Documentação API Quantum

Integre seus agentes, chatbots, CRM e automações a bases de conhecimento do IPBX Quantum usando a API REST.

API v1 · JSON · Bearer Token Base URL: https://rag1.ipbx.com.br
Importante: a documentação é pública, mas os dados são privados. Operações protegidas exigem uma API key válida do seu tenant. Guarde a chave no backend ou em um cofre de segredos. O login do painel não deve ser usado como autenticação de integrações externas.
01

Começar

Use uma chave API criada no painel do Quantum. Nunca coloque a chave em frontend público.

export QUANTUM_API_KEY="rag_SUA_CHAVE"
export BASE_URL="https://rag1.ipbx.com.br"
curl -sS "$BASE_URL/api/v1/capabilities"
02

Autenticação

As chamadas externas usam Authorization: Bearer rag_...; cada chave pertence a uma organização.

curl -sS -H "Authorization: Bearer $QUANTUM_API_KEY" \
  "$BASE_URL/api/v1/knowledge-bases"
03

Criar base de conhecimento

Cria uma base dentro da organização autorizada.

curl -sS -X POST "$BASE_URL/api/v1/knowledge-bases" \
  -H "Authorization: Bearer $QUANTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Manual do Atendimento"}'
# Resposta contém id e name. Guarde o id como BASE_ID.
04

Configurar embedding

O provedor é definido uma única vez por base: local ou openai. Uma alteração requer criar nova base.

export BASE_ID="UUID_DA_BASE"
curl -sS -X PUT "$BASE_URL/api/v1/knowledge-bases/$BASE_ID/embedding-profile" \
  -H "Authorization: Bearer $QUANTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"local"}'
05

Enviar PDF

Upload multipart/form-data. O processamento é assíncrono, com status a consultar.

curl -sS -X POST "$BASE_URL/api/v1/knowledge-bases/$BASE_ID/documents" \
  -H "Authorization: Bearer $QUANTUM_API_KEY" \
  -F "file=@manual.pdf"
# HTTP 202: documento aceito; consulte o status posteriormente.
06

Consultar documentos

Liste os documentos ou consulte um documento específico depois de receber seu ID.

curl -sS "$BASE_URL/api/v1/knowledge-bases/$BASE_ID/documents" \
  -H "Authorization: Bearer $QUANTUM_API_KEY"
export DOCUMENT_ID="UUID_DO_DOCUMENTO"
curl -sS "$BASE_URL/api/v1/knowledge-bases/$BASE_ID/documents/$DOCUMENT_ID" \
  -H "Authorization: Bearer $QUANTUM_API_KEY"
07

Busca semântica

Retorna trechos e scores para que seu agente use as evidências recuperadas.

curl -sS -X POST "$BASE_URL/api/v1/knowledge-bases/$BASE_ID/semantic-search" \
  -H "Authorization: Bearer $QUANTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Qual é o procedimento de suporte?","limit":5}'
08

Resposta fundamentada (opcional)

Disponível somente quando o provedor de geração de respostas estiver configurado; sem ele, o endpoint retorna 503.

curl -sS -X POST "$BASE_URL/api/v1/knowledge-bases/$BASE_ID/answers" \
  -H "Authorization: Bearer $QUANTUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Qual é o procedimento de suporte?","limit":5}'
# Resposta inclui answer, sources, model e grounded.
09

Consumo e limites

Consulte o uso e respeite as cotas do plano de sua organização.

curl -sS "$BASE_URL/api/v1/usage" \
  -H "Authorization: Bearer $QUANTUM_API_KEY"

Erros e boas práticas

401: API key inválida ou ausente. 403: acesso negado. 404: recurso não encontrado na organização. 409: perfil de embedding ausente ou incompatível. 413/415: tamanho ou tipo de PDF inválido. 422: parâmetros inválidos. 429: cota excedida, quando aplicável. 503: serviço de geração indisponível.

Use HTTPS, tempos limite adequados, retry com backoff para erros transitórios e nunca exponha chaves no navegador. Os limites reais dependem do plano e configuração do servidor.

Swagger e OpenAPI

A especificação interativa do FastAPI está em https://rag1.ipbx.com.br/docs e o OpenAPI em /openapi.json. Se alguma rota não constar desta página, consulte a versão publicada no Swagger.