Endpoints

Referencia completa de todos os endpoints da API BuildShip — confere com o codigo.

Copiar como .md

Todos os endpoints aceitam JSON e retornam JSON. Base URL: https://api.buildship.com.br/api/v1.

Fonte da verdade: GET /api/v1/docs retorna o catálogo de endpoints diretamente do servidor (atualizado em runtime). Esta página é a versão narrada para humanos.

Health Check

GET /api/v1/health

Sem autenticacao. Retorna o status do servico e a lista resumida de endpoints.

{
  "status": "ok",
  "version": "1.0.0",
  "endpoints": { "...": "..." }
}

---

Process — Arquivo + prompt

Endpoint principal pra processar arquivos com IA.

POST /api/v1/process
Content-Type: multipart/form-data

Permissao: process

Campos:

Campo	Tipo	Obrigatorio	Descricao
file	file	sim	Arquivo a processar (max 500MB)
prompt	string	sim	Instrucao pra IA
templateId	string	nao	ID de template (substitui prompt)
templateVars	object	nao	Variaveis do template
endUserId	string	nao	ID do usuario final (B2B2C)
callbackUrl	string	nao	URL pra receber resultado via webhook

Exemplo:

curl -X POST https://api.buildship.com.br/api/v1/process \
  -H "X-API-Key: bld_sua_chave" \
  -F "file=@curriculo.pdf" \
  -F "prompt=Extraia nome, email e telefone deste curriculo"

Resposta:

{
  "sessionId": "session_abc123",
  "status": "started",
  "fileUrl": "https://r2.buildship.com.br/.../curriculo.pdf"
}

Process Batch (lote)

POST /api/v1/process/batch
Content-Type: multipart/form-data

Envia vários arquivos numa única chamada. Mesmos campos do /process, mas file aceita N arquivos (campo repetido).

curl -X POST https://api.buildship.com.br/api/v1/process/batch \
  -H "X-API-Key: bld_sua_chave" \
  -F "file=@cv1.pdf" \
  -F "file=@cv2.pdf" \
  -F "file=@cv3.pdf" \
  -F "prompt=Extraia nome e email"

Resposta: array de { sessionId, status, fileUrl } — um por arquivo.

Status / detalhes de um processamento

GET /api/v1/process/:id

Retorna status atual, output (quando completed), tokens, custo.

Listar processamentos

GET /api/v1/process?limit=20&offset=0&status=completed

Filtros opcionais: status, endUserId, templateId.

Download de arquivo gerado

GET /api/v1/process/:id/download

Pra processamentos cuja saída é binária (imagem, áudio, vídeo). Retorna o arquivo direto, com Content-Type apropriado.

---

Chat — Conversa multi-turn

Pra mensagens sem arquivo (ou com texto/contexto inline), multi-turn.

POST /api/v1/chat
Content-Type: application/json

Permissao: chat

Body:

{
  "message": "Sua mensagem aqui",
  "sessionId": "session_existente_opcional",
  "endUserId": "user-123",
  "templateId": "tmpl_xyz",
  "templateVars": { "nome": "Joao" },
  "fileContent": "texto inline opcional"
}

Multi-turn (mesma sessao):

# Primeira mensagem
curl -X POST .../api/v1/chat \
  -H "X-API-Key: bld_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"message": "Ola", "endUserId": "user-1"}'
# → { "sessionId": "session_abc", "status": "started" }

# Segunda (passa o sessionId)
curl -X POST .../api/v1/chat \
  -H "X-API-Key: bld_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"message": "E ai?", "sessionId": "session_abc"}'
# → { "sessionId": "session_abc", "status": "resumed" }

Status / mensagens de uma sessao

GET /api/v1/chat/:sessionId

Resposta:

{
  "id": "session_abc",
  "status": "completed",
  "messages": [
    { "role": "user", "content": "...", "timestamp": "..." },
    { "role": "assistant", "content": "...", "timestamp": "..." }
  ],
  "lastOutput": "Resposta final da IA",
  "tokensUsed": 1234,
  "creditsUsed": 12,
  "createdAt": "2026-04-28T10:00:00Z",
  "endUserId": "user-123"
}

Stream em tempo real (SSE)

GET /api/v1/chat/:sessionId/stream

Server-Sent Events com chunks da IA conforme ela responde.

Listar sessoes

GET /api/v1/chat/sessions
GET /api/v1/chat/sessions?endUserId=user-123
GET /api/v1/chat/sessions?limit=20&offset=0

Filtros: endUserId, status, limit (default 20, max 100), offset.

---

B2B Send — Hibrido

Aceita arquivo + prompt + sessao numa unica chamada. Util pra automacoes.

POST /api/v1/b2b/send
Content-Type: multipart/form-data

Permissao: b2bSend

Funciona como /process se tiver file, ou como /chat se nao tiver. Permite continuar sessao existente passando sessionId.

---

Templates

Prompts reusaveis com variaveis {{nome}}. Detalhe completo em Templates.

Metodo	Path	Descricao
GET	/api/v1/templates	Lista seus templates
GET	/api/v1/templates/:id	Busca um template
POST	/api/v1/templates	Cria template via JSON
POST	/api/v1/templates/upload	Cria template enviando arquivo (.md, .txt)
PUT	/api/v1/templates/:id	Atualiza template
DELETE	/api/v1/templates/:id	Remove template

Permissao: templates

---

Conta e uso

GET /api/v1/account

Retorna creditos, plano, limites e estatisticas resumidas.

GET /api/v1/usage

Detalhamento de uso (consumo por dia, tokens, custo, breakdown por endpoint).

---

End Users (multi-tenancy via parametro)

Importante: hoje não existem endpoints REST separados pra gerenciar end users (POST /end-users etc). End users são "criados" implicitamente: basta passar endUserId em qualquer chamada de /chat, /process ou /b2b/send.

Como funciona:

• O endUserId que você manda é gravado na sessão.
• Sessões/mensagens ficam isoladas por endUserId (filtros nas listagens).
• Se o projeto tem apiMemoryPerUser=true, a IA mantém um perfil .md por endUser em .brain/api/db/users/<endUserId>.md, usado como contexto em conversas futuras.

Roadmap: endpoints REST dedicados (/api/v1/end-users) estao no backlog. Por enquanto, use o parametro endUserId direto.

---

Knowledge Base (via .brain do projeto)

Importante: também não há CRUD REST pra knowledge base. O conhecimento extra que a IA usa como contexto vive em arquivos .md dentro de .brain/api/db/ do seu projeto.

Pra alimentar a knowledge base:

1. Crie/edite arquivos .md em .brain/api/db/ via o painel do projeto (modo apiEnabled).
2. A IA injeta esse conteúdo no system prompt em toda chamada /chat ou /process daquele projeto.

Roadmap: API REST pra CRUD da knowledge base está no backlog.

---

Catalogo JSON (auto-atualizado)

Pra clientes/SDKs/automacoes, o catalogo completo de endpoints (com permissoes, parametros, headers) está em:

GET /api/v1/docs

Esse JSON é gerado a partir do código — sempre reflete o que o servidor realmente expõe.