Agents

Start an agent run

Starts a workspace-scoped agent conversation for the specified Bubble app and immediately queues the initial prompt.

POST /api/public/v1/agents

Start an agent run

curl --request POST \
  --url 'https://api.buildprint.ai/api/public/v1/agents' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "key": "value"
}'
{
  "agentId": "<string>",
  "kind": "<string>",
  "status": "queued",
  "appId": "<string>",
  "projectId": "<string>",
  "createdAt": 1
}

Agent accepted

Authorizations

  • Authorization string required header

    Workspace REST API token prefixed with bp_

Request Body

application/json
  • appId string required

    Bubble app ID for the workspace project this request targets.

  • prompt string required

    User prompt to send to the model.

  • model string enum required enum

    Model identifier to use for the run. 10 allowed enum values.

  • reasoningEffort string enum enum

    Requested reasoning effort for the selected model. Allowed values: none, low, medium, high.

  • permission string enum enum

    Whether the run can only inspect the app or is also allowed to make edits. Allowed values: read_only, allow_edits.

  • permittedBranches[] string array

    Branches the run is allowed to access when branch restrictions apply.

  • completionWebhookUrl string (uri)

    Webhook URL Buildprint will call when the run completes.

  • userEmail string (email)

    Email of the Buildprint user whose provider credentials should be used.

Response

application/json
  • agentId string

    Opaque identifier for the linked agent conversation.

  • kind string

    Discriminator describing the kind of object returned.

  • status string enum enum

    Current high-level lifecycle state for the asynchronous run. Allowed values: queued, running, completed, error.

  • appId string

    Bubble app ID for the workspace project this request targets.

  • projectId string

    Opaque identifier for the workspace project.

  • createdAt number

    Unix timestamp in milliseconds when the resource was created.