Endpoints

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:

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.

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.