Skip to main content
POST
/
v0
/
agents
Launch an agent
curl --request POST \
  --url https://cloud.firebender.com/v0/agents \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "prompt": {
    "text": "Add a README.md file with installation instructions",
    "images": [
      {
        "data": "iVBORw0KGgoAAAANSUhEUgAA...",
        "dimension": {
          "width": 2,
          "height": 2
        }
      }
    ]
  },
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "model": "claude-sonnet-4-20250514",
  "target": {
    "autoCreatePr": false,
    "branchName": "feature/add-readme"
  },
  "webhook": {
    "url": "https://example.com/webhooks/firebender-agent",
    "secret": "your-webhook-secret-key-minimum-32-characters"
  }
}
'
{
  "id": "fb_abc123xyz789",
  "name": "Add README Documentation",
  "status": "CREATING",
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  },
  "target": {
    "url": "https://firebender.com/agents?id=fb_abc123xyz789",
    "branchName": "firebender/abc123xyz789",
    "prUrl": "https://github.com/your-org/your-repo/pull/1234",
    "autoCreatePr": false
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "summary": "Added README.md with installation instructions and usage examples"
}

Authorizations

​
X-API-Key
string
header
required

API key from Firebender Dashboard

Body

application/json
​
prompt
object
required
​
source
object
required
​
model
string

The LLM to use

Minimum string length: 1
Example:

"claude-sonnet-4-20250514"

​
target
object
​
webhook
object

Response

Agent created successfully

​
id
string
required

Unique identifier for the cloud agent

Example:

"fb_abc123xyz789"

​
name
string
required

Name for the agent (derived from prompt)

Example:

"Add README Documentation"

​
status
enum<string>
required

Current status of the cloud agent:

  • CREATING: VM is being provisioned
  • RUNNING: Agent is actively working
  • FINISHED: Agent completed successfully
  • ERROR: Agent encountered an error
  • EXPIRED: Agent timed out
Available options:
CREATING,
RUNNING,
FINISHED,
ERROR,
EXPIRED
​
source
object
required
​
target
object
required
​
createdAt
string<date-time>
required

When the agent was created

Example:

"2024-01-15T10:30:00Z"

​
summary
string

Summary of the agent's work (available after completion)

Example:

"Added README.md with installation instructions and usage examples"