Introdução

O Buildprint expõe uma API REST para implantar e gerenciar programaticamente agentes que trabalham no seu aplicativo 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 é exibido apenas 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 na interface do Buildprint interrompe todas as requisições futuras imediatamente.

Modelos e propriedade de execução

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

• Modelos Anthropic e OpenAI exigem 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 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 executada.

• running: o Buildprint está executando ativamente a operação.

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

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

Webhooks de conclusão

Tanto as requisiçõ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 faz um POST de um payload JSON 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 monitora 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 tenta novamente até 3 vezes, aguardando 30 segundos entre as tentativas.

Respostas de erro

Cada 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 userEmail.

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

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