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.
Use the API to create a new Project, or add a branch to an existing Project, with your prompt. A link to the Visual Editor, where you can monitor progress, is returned in the response.
- Builder creates a new Project in your Space or adds a branch to an existing Project.
- 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 is returned as soon as the Project branch is created—typically within 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 | No | ID of an existing project to run the task in. If omitted, a new project is created automatically. |
| String | No | A friendly name for the new branch. Also used as the project name when creating a new project. |
| 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. You must be an Admin to retrieve theuserId.userEmailis the email address associated with the user's Builder account.
To run the agent in an existing project, pass the project's ID in the projectId field:
{
"projectId": "<your-project-id>",
"userMessage": {
"userPrompt": "Add a dark mode toggle to the settings page"
}
}The provided Project must belong to the same Builder Space as the API key used in authentication.
To find your Project's ID, go to your Project settings, as shown in the video below.
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 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. |
|