Introduction

Get Started

Create a browser workflow as an automation, run it as a job, and retrieve its results with the Browser Fleet API.

Base URL

Every endpoint path in this reference is relative to this origin.

https://api.browserfleet.dev

Authentication

Get your organization's API key with Account → Sign In, then Get API Key. Send it as a bearer token in the Authorization header, or use the x-api-key header. If both are present, Authorization takes precedence. Keep your API key private.

Authorization: Bearer <api_key>
x-api-key: <api_key>

Quick Start

Set BROWSER_FLEET_API_KEY in your environment. To use your own vendors, configure their keys first. Replace the example URL and IDs with your own values. Create an automation, start a job, and poll until it is Done or Error.

1. Create Automation — Request (cURL)

curl -X POST "https://api.browserfleet.dev/rest/public/automations" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Portal dataset export",
    "task": "Download the complete dataset from %portalUrl as a CSV file.",
    "output": {},
    "storage": [
      {
        "name": "dataset.csv",
        "description": "The complete dataset exported as CSV"
      }
    ],
    "steps": [
      "Open %portalUrl.",
      "Click the Export CSV button to download the complete dataset."
    ],
    "stealthConfiguration": "WARP"
  }'

1. Create Automation — Response (JSON)

{
  "automationId": "3f9c2b1e-8a4d-4c6e-9b7a-2d5e8f1a0c34",
  "createdAt": "2026-06-17T10:00:00.000Z",
  "name": "Portal dataset export",
  "task": "Download the complete dataset from %portalUrl as a CSV file.",
  "output": {},
  "storage": [
    {
      "name": "dataset.csv",
      "description": "The complete dataset exported as CSV"
    }
  ],
  "steps": [
    "Open %portalUrl.",
    "Click the Export CSV button to download the complete dataset."
  ],
  "stealthConfiguration": "WARP",
  "webhookUrl": null,
  "maxConcurrency": null
}

2. Start Job — Request (cURL)

curl -X POST "https://api.browserfleet.dev/rest/public/jobs" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "automationId": "3f9c2b1e-8a4d-4c6e-9b7a-2d5e8f1a0c34",
    "priority": 10,
    "variables": {
      "%portalUrl": "https://example.com/registry"
    }
  }'

2. Start Job — Response (JSON)

{
  "automationId": "3f9c2b1e-8a4d-4c6e-9b7a-2d5e8f1a0c34",
  "jobId": "7b2e4d9a-1c3f-4e8b-a6d5-0f9c2b8e3a71",
  "priority": 10,
  "status": "Pending"
}

3. Poll Job — Request (cURL)

curl "https://api.browserfleet.dev/rest/public/jobs?jobId=7b2e4d9a-1c3f-4e8b-a6d5-0f9c2b8e3a71" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY"

3. Poll Job — Done Response (JSON)

{
  "automationId": "3f9c2b1e-8a4d-4c6e-9b7a-2d5e8f1a0c34",
  "createdAt": "2026-06-17T10:01:00.000Z",
  "error": null,
  "jobId": "7b2e4d9a-1c3f-4e8b-a6d5-0f9c2b8e3a71",
  "metadata": {},
  "priority": 10,
  "result": {
    "data": {},
    "storage": [
      {
        "name": "dataset.csv",
        "id": "4f9a2c7e1b3d4a5f8e6c0b9d2a7f1e3c"
      }
    ]
  },
  "status": "Done",
  "updatedAt": "2026-06-17T10:04:00.000Z"
}

Errors

Request errors use HTTP error statuses and JSON. Execution failures remain retrievable jobs with status Error, a null result, and an error object containing a stable code and a diagnostic trace.

Common Browser Fleet API error responses
Status	Body	Meaning
400	{ "error": "Invalid or missing JSON body" }, { "error": "Invalid request body", "issues": { ... } }, or { "error": "Missing ...Id" }	The JSON body, query string, or a required field is invalid. Validation errors include an issues object.
401	{ "error": "Invalid API key" }	The request did not include a valid API key.
404	{ "error": "Automation not found" }, { "error": "Job not found" }, or { "error": "File not found or deleted after the 7-day retention period" }	The requested resource could not be found.
500	{ "error": "Internal server error" }	An unexpected server error stopped the request.