API Vulgate — visão geral

A plataforma Vulgate expõe tudo o que o aplicativo web faz através de uma API REST + JSON. Seja para construir uma ferramenta interna, um pipeline de pesquisa ou um produto voltado para clientes, a API é seu ponto de acesso para ingestão, busca e chat com IA.

As três APIs

API	O que faz	Referência
Ingestão	Enviar arquivos, iniciar trabalhos de ingestão, monitorar progresso, gerenciar documentos.	/developers/ingest/overview
Busca	Executar busca neural ou por palavra-chave em sua Biblioteca. Retorna passagens ou IDs de documentos.	/developers/search/overview
Chat	Endpoint de Chat Completions compatível com OpenAI fundamentado na sua Biblioteca.	/developers/chat/overview

A API de Chat usa o formato OpenAI Chat Completions, então a maioria dos SDKs existentes (Python openai, Vercel ai, LangChain, etc.) funciona apenas apontando-os para https://vulgate.ai/api com sua chave de API Vulgate.

URL base

https://vulgate.ai/api

Todos os endpoints são apenas HTTPS.

Autenticação

Toda requisição precisa de um token Bearer no cabeçalho Authorization:

Authorization: Bearer <sua-chave-api>

Veja Criando uma chave de API para saber como gerar uma.

Exemplo rápido

Execute uma busca na sua Biblioteca:

curl -G "https://vulgate.ai/api/search" \
  -H "Authorization: Bearer $VULGATE_API_KEY" \
  --data-urlencode "search=teologia eucarística" \
  --data-urlencode "mode=neural" \
  --data-urlencode "per_page=5"

A resposta é um objeto JSON com uma lista de passagens de resultado, cada uma com o ID do documento, um índice, o conteúdo renderizado e os metadados do documento fonte. Veja a referência da API de Busca para cada campo.

Streaming

A API de Chat suporta respostas em streaming no formato OpenAI Chat Completions. Defina stream: true no corpo da requisição. Veja a visão geral da API de Chat.

Limites de taxa

A API de Chat impõe um limite de taxa de janela deslizante de 10 requisições por 10 segundos por equipe, com um timeout de execução por requisição de 120 segundos. A API de Busca tem um timeout de execução por requisição de 40 segundos. Quando você excede um limite, a API retorna HTTP 429.

SDKs

O Vulgate atualmente não disponibiliza um SDK próprio, mas a API de Chat é intencionalmente compatível com o cliente OpenAI. Aponte o SDK OpenAI para https://vulgate.ai/api e passe sua chave de API Vulgate:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.VULGATE_API_KEY,
  baseURL: "https://vulgate.ai/api",
});

Para as APIs de Ingestão e Busca, qualquer cliente HTTP (fetch, axios, requests) funciona.