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

Bearer token

curl 'https://api.buildprint.ai/api/public/v1/agents' \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "appId": "app_01JXY9AZK4KV",
  "prompt": "example",
  "model": "claude-fable-5",
  "reasoningEffort": "none",
  "serviceTier": "default",
  "permission": "read_only",
  "permittedBranches": [
    "example"
  ],
  "completionWebhookUrl": "https://example.com",
  "userEmail": "[email protected]"
}'

{
  "agentId": "agent_01JXY9AZK4KV",
  "kind": "example",
  "status": "queued",
  "appId": "app_01JXY9AZK4KV",
  "projectId": "project_01JXY9AZK4KV",
  "createdAt": 1
}

Agent accepted

Body

· CreateAgentRequest

required application/json

Configuration for the agent run to create.

appId string · min length: 1 required

Bubble app ID for the workspace project this request targets.

prompt string · min length: 1 required

User prompt to send to the model.

model ChatModelId · enum required

Model identifier to use for the run.

values

claude-fable-5
claude-fable-5.1
claude-opus-5
claude-sonnet-5
openai-gpt-6-astra
openai-gpt-5.6-sol

reasoningEffort string · enum

Requested reasoning effort for the selected model.

values

none
low
medium
high

serviceTier string · enum

Requested speed for the selected model. Fast is available for supported Codex and Cursor models.

values

default
fast

permission string · enum

Whether the run can only inspect the app or is also allowed to make edits.

values

read_only
allow_edits

permittedBranches array of string · max items: 50

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

completionWebhookUrl string · uri

Webhook URL Buildprint will call when the run completes.

Body

Responses