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 ```http GET /api/v1/health ``` Sem autenticacao. Retorna o status do servico e a lista resumida de endpoints. ```json { "status": "ok", "version": "1.0.0", "endpoints": { "...": "..." } } ``` --- ## Process — Arquivo + prompt Endpoint principal pra processar arquivos com IA. ```http 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:** ```bash 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:** ```json { "sessionId": "session_abc123", "status": "started", "fileUrl": "https://r2.buildship.com.br/.../curriculo.pdf" } ``` ### Process Batch (lote) ```http 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). ```bash 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 ```http GET /api/v1/process/:id ``` Retorna status atual, output (quando `completed`), tokens, custo. ### Listar processamentos ```http GET /api/v1/process?limit=20&offset=0&status=completed ``` Filtros opcionais: `status`, `endUserId`, `templateId`. ### Download de arquivo gerado ```http 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. ```http POST /api/v1/chat Content-Type: application/json ``` **Permissao**: `chat` **Body:** ```json { "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):** ```bash # 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 ```http GET /api/v1/chat/:sessionId ``` **Resposta:** ```json { "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) ```http GET /api/v1/chat/:sessionId/stream ``` Server-Sent Events com chunks da IA conforme ela responde. ### Listar sessoes ```http 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. ```http 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](/docs/api/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 ```http GET /api/v1/account ``` Retorna creditos, plano, limites e estatisticas resumidas. ```http 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: ```http GET /api/v1/docs ``` Esse JSON é gerado a partir do código — sempre reflete o que o servidor realmente expõe.