All Collections

Getting started

Buildprint exposes a REST API for deploying and managing agents, code reviews, automations, and project tests for your Bubble apps.

The public REST API is currently in beta. The endpoints are available now, but the surface area may change as the product evolves.

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 Agent > 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://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 app IDs 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.

  • Connected provider 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

Agent and code review creation requests can include completionWebhookUrl. When provided, Buildprint waits for the run to reach a terminal state and then sends a JSON payload to your endpoint.

  • Standalone agent runs send agent.completed.

  • Code review runs send review.completed.

  • If your webhook returns a non-2xx response, Buildprint retries the request.

Error responses

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

Common errors include:

  • 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 connected provider 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.

Was this helpful?