Use the Agents Run API to trigger Builder's AI agent programmatically from your own systems—for example, from a CI pipeline, an internal tool, or an automated workflow. The agent creates a new Project, runs your prompt, and returns a link to the Visual Editor where you can monitor progress.
- Builder creates a new Project in your Space with an auto-generated name based on your prompt.
- Builder creates a branch on that Project and provisions a cloud container.
- The AI agent begins working on your prompt in the background.
- Open the
urlfrom the response to observe the agent work in real time in the Visual Editor.
The response returns as soon as the branch is create—typically a few seconds—while the AI agent continues working independently.
Send a POST request to this URL, replacing {spaceId} with your Builder Public API Key.
POST https://api.builder.io/agents/run?apiKey={spaceId}Authenticate with your Builder Private API Key using a Bearer token.
Authorization: Bearer bpk-YOUR_PRIVATE_KEYThe request body is a JSON object with the following fields.
| Field | Type | Required | Description |
|---|---|---|---|
| object | Yes | The message to send to the AI agent. |
| String | Yes | The prompt describing what you want the agent to build. |
| array | No | File or image attachments for context. See Attachments. |
| String | Conditional | The Builder user ID to associate with this run. Provide |
| String | Conditional | The email of a Builder user in your Space. Provide |
You must provide either userId or userEmail to identify which Builder user the agent acts on behalf of. The user must be a member of the Space identified by the apiKey.
userIdis the Builder user ID. Find the user ID in the Space Settings.userEmailis the email address associated with the user's Builder account.
Provide images, files, or URLs as context for the AI agent. The attachments array supports several attachment types, each suited to different use cases.
Upload an image, PDF, JSON file, or plain text file. The agent uses these as visual or textual context when generating code.
| Field | Type | Required | Description |
|---|---|---|---|
| String | Yes | Must be |
| String | Yes | The filename; for example, |
| String | Yes | The MIME type of the file. See supported content types below. |
| String | Yes | A data URL containing the base64-encoded file content; for example, |
| Number | Yes | File size in bytes. |
| String | Yes | A unique identifier for this attachment; for example, a UUID. |
| String | No | Extracted text content. Useful for PDFs or text files where you want to provide the raw text alongside the file. |
Supported content types:
| Content type | Use case |
|---|---|
| Screenshots, design mockups, UI references |
| Photos, compressed screenshots |
| Modern image format, smaller file sizes |
| Animated examples, short interaction demos |
| Design specs, requirements documents |
| API response samples, configuration files |
| Plain text files, logs, specs |
Image upload example:
{
"type": "upload",
"name": "hero-mockup.png",
"contentType": "image/png",
"dataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
"size": 204800,
"id": "att-001"
}PDF spec example:
{
"type": "upload",
"name": "requirements.pdf",
"contentType": "application/pdf",
"dataUrl": "data:application/pdf;base64,JVBERi0xLjQK...",
"size": 512000,
"id": "att-002",
"text": "The landing page should include a hero section with..."
}Point the agent to a live webpage for inspiration or reference. The agent fetches and analyzes the page before generating code.
| Field | Type | Required | Description |
|---|---|---|---|
| String | Yes | Must be |
| String | Yes | A fully qualified URL; for example, |
For example:
{
"type": "url",
"value": "https://stripe.com/pricing"
}You can combine different attachment types in a single request. For example, provide a design mockup image alongside a reference URL:
"attachments": [
{
"type": "upload",
"name": "design.png",
"contentType": "image/png",
"dataUrl": "data:image/png;base64,iVBORw0KGgo...",
"size": 150000,
"id": "att-001"
},
{
"type": "url",
"value": "https://example.com/style-guide"
}
]The endpoint returns 202 Accepted with a JSON body once the branch is created. The AI agent continues working in the background.
| Field | Type | Description |
|---|---|---|
| String | The generated branch name where the agent is working. |
| String | The ID of the newly created project. |
| String | Direct link to the Builder Visual Editor for this branch. |
| String | Always |
The following examples show a minimal request and a request with attachments.
curl -X POST "https://api.builder.io/agents/run?apiKey=YOUR_SPACE_ID" \
-H "Authorization: Bearer bpk-YOUR_PRIVATE_KEY" \
-H "Content-Type: application/json" \
-d '{
"userMessage": {
"userPrompt": "Build a landing page with a hero section, feature grid, and contact form"
},
"userEmail": "developer@yourcompany.com"
}'{
"branchName": "landing-page-hero-a1b2",
"projectId": "abc123def456",
"url": "https://builder.io/app/projects/abc123def456/landing-page-hero-a1b2",
"status": "processing"
}curl -X POST "https://api.builder.io/agents/run?apiKey=YOUR_SPACE_ID" \
-H "Authorization: Bearer bpk-YOUR_PRIVATE_KEY" \
-H "Content-Type: application/json" \
-d '{
"userMessage": {
"userPrompt": "Recreate this design as a responsive landing page",
"attachments": [
{
"type": "upload",
"name": "design-mockup.png",
"contentType": "image/png",
"dataUrl": "data:image/png;base64,iVBORw0KGgo...",
"size": 204800,
"id": "att-001"
}
]
},
"userEmail": "developer@yourcompany.com",
}'If the request fails, the API returns one of the following error responses.
| Status | Meaning | Example |
|---|---|---|
| Missing or invalid fields. |
|
| No user identifier provided. |
|
| Invalid private key, mismatched Space, or user not in space. |
|
| User not found. |
|
| Unexpected server error. |
|