Endpoints

Referencia completa de todos os endpoints da API BuildShip.

Copiar como .md

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

Health Check

GET /api/v1/health

Sem autenticacao. Retorna { "status": "ok", "version": "1.0.0" }.

---

Process — Arquivo + prompt

Endpoint principal pra processar arquivos com IA.

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

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"
}

---

Chat — Conversa simples

Pra mensagens sem arquivo, multi-turn.

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

Body:

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

Multi-turn (mesma sessao):

# Primeira mensagem
curl -X POST .../api/v1/chat -d '{"message": "Ola"}'
# → { "sessionId": "session_abc", "status": "started" }

# Segunda (passa o sessionId)
curl -X POST .../api/v1/chat -d '{"message": "E ai?", "sessionId": "session_abc"}'
# → { "sessionId": "session_abc", "status": "resumed" }

---

B2B Send — Hibrido

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

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

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

---

Sessions

Listar sessoes

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

Buscar sessao especifica

GET /api/v1/sessions/: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/sessions/:sessionId/stream

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

---

End Users (B2B2C)

Crie/liste usuarios finais da sua API pra cobrar por uso individual.

POST /api/v1/end-users
GET /api/v1/end-users
GET /api/v1/end-users/:id
PUT /api/v1/end-users/:id
DELETE /api/v1/end-users/:id

Body:

{
  "externalId": "user-123",
  "name": "Cliente Final",
  "email": "cliente@exemplo.com",
  "metadata": { "plano": "premium" }
}

---

Knowledge Base

Base de conhecimento por integracao — usada como contexto extra pela IA.

GET /api/v1/knowledge-base
POST /api/v1/knowledge-base
PUT /api/v1/knowledge-base/:id
DELETE /api/v1/knowledge-base/:id

---

Conta e uso

GET /api/v1/account

Retorna creditos, plano, limites e estatisticas de uso.