Introdução

O Buildprint expõe uma API REST para implantar e gerenciar programaticamente agentes que trabalham em seu app Bubble.

URL Base

A API REST está exposta em https://api.buildprint.ai/api/public/v1

Esquema OpenAPI

curl https://api.buildprint.ai/api/public/v1/openapi.json

Criar um token

1. Peça a um administrador do workspace para abrir Integrations > API no Buildprint.

2. Crie um token de API REST e dê a ele um nome descritivo.

3. Armazene o token bp_... retornado de forma segura. Ele só é exibido uma vez.

4. Envie o token em cada requisição autenticada como Authorization: Bearer bp_....

Os tokens podem ser limitados a todos os projetos no workspace ou a projetos específicos.

Início rápido

BASE_URL="https://www.api.buildprint.ai/api/public/v1"
TOKEN="bp_your_workspace_token"

curl --request POST "$BASE_URL/agents" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "appId": "your-bubble-app-id",
    "prompt": "Inspect the checkout flow and tell me why the webhook retry path fails.",
    "model": "buildprint-gpt-5.3-codex"
  }'

curl --request GET "$BASE_URL/agents/<agentId>" \
  --header "Authorization: Bearer $TOKEN"

Autenticação e escopo

• Os tokens da API REST são limitados a um único workspace.

• Um token só pode ser usado para valores de appId de projetos Buildprint verificados dentro desse workspace.

• Revogar um token a partir da interface do Buildprint interrompe todas as requisições futuras imediatamente.

Modelos e propriedade de execução

• Os modelos hospedados pelo Buildprint usam o saldo de créditos do workspace e podem ser executados sem o userEmail.

• Modelos da Anthropic e OpenAI exigem o userEmail de um membro do workspace que possua credenciais de provedor ativas conectadas no workspace do Buildprint.

• Os valores de esforço de raciocínio (reasoning effort) são none, low, medium e high. O padrão é medium.

• Os valores de permissão são read_only e allow_edits. O padrão é read_only.

Status

• queued: a execução foi aceita e está aguardando para ser processada.

• running: o Buildprint está executando ativamente a tarefa.

• completed: o agente ou a revisão terminou com sucesso.

• error: a execução foi encerrada com um erro. Consulte lastError quando disponível.

Webhooks de conclusão

Tanto as solicitações de criação de agente quanto as de revisão de código aceitam completionWebhookUrl. Quando fornecido, o Buildprint aguarda a execução atingir um estado terminal e então envia um payload JSON (via POST) para o seu endpoint.

• Execuções de agentes independentes enviam agent.completed.

• Execuções de revisão de código enviam review.completed.

• O Buildprint consulta a execução a cada 5 segundos até que ela atinja completed ou error.

• Se o seu webhook retornar uma resposta não-2xx, o Buildprint tentará novamente até 3 vezes, aguardando 30 segundos entre as tentativas.

Respostas de erro

Toda resposta de erro inclui uma string error. Algumas respostas também incluem um code legível por máquina e, para verificações de plano, um reason.

• 401 Unauthorized: token bearer ausente ou inválido.

• 402 api_access_required: o plano do workspace não inclui acesso à API.

• 402 insufficient_paid_credits: um modelo hospedado pelo Buildprint foi solicitado, mas o workspace não possui créditos pagos suficientes.

• 400 user_email_required: um modelo Claude ou OpenAI foi solicitado sem o userEmail.

• 403 user_not_workspace_member: o userEmail fornecido não é um membro do workspace.

• 403 missing_provider_credentials: o usuário fornecido está no workspace, mas não possui credenciais ativas para o provedor solicitado.