Getting started

Buildprint exposes a REST API for programatically deploying and managing agents that work on your Bubble app.

Base URL

The REST API is exposed at https://api.buildprint.ai/api/public/v1

OpenAPI Schema

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

Create a token

1. Ask a workspace admin to open Integrations > API in Buildprint.

2. Create a REST API token and give it a descriptive name.

3. Store the returned bp_... token securely. It is only shown once.

4. Send the token on every authenticated request as Authorization: Bearer bp_....

Tokens can be scoped to all projects in the workspace, or to specific projects.

Quick start

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"

Authentication and scope

• REST API tokens are scoped to a single workspace.

• A token can only be used for appId values for verified Buildprint projects inside that workspace.

• Revoking a token from the Buildprint UI stops all future requests immediately.

Models and execution ownership

• Buildprint-hosted models use the workspace credit balance and can run without userEmail.

• Anthropic and OpenAI models require userEmail for a workspace member who has active provider credentials connected in the Buildprint workspace.

• Reasoning effort values are none, low, medium, and high. The default is medium.

• Permission values are read_only and allow_edits. The default is read_only.

Statuses

• queued: the run has been accepted and is waiting to execute.

• running: Buildprint is actively executing the run.

• completed: the agent or review finished successfully.

• error: the run terminated with an error. See lastError when available.

Completion webhooks

Both agent and code review creation requests accept completionWebhookUrl. When provided, Buildprint waits for the run to reach a terminal state and then POSTs a JSON payload to your endpoint.

• Standalone agent runs send agent.completed.

• Code review runs send review.completed.

• Buildprint polls the run every 5 seconds until it reaches completed or error.

• If your webhook returns a non-2xx response, Buildprint retries up to 3 times, waiting 30 seconds between attempts.

Error responses

Every error response includes an error string. Some responses also include a machine-readable code and, for plan checks, a reason.

• 401 Unauthorized: missing or invalid bearer token.

• 402 api_access_required: the workspace plan does not include API access.

• 402 insufficient_paid_credits: a Buildprint-hosted model was requested but the workspace does not have enough paid credits.

• 400 user_email_required: a Claude or OpenAI model was requested without userEmail.

• 403 user_not_workspace_member: the supplied userEmail is not a member of the workspace.

• 403 missing_provider_credentials: the supplied user is in the workspace but has no active credentials for the requested provider.