API Reference

Automations

Automations are immutable browser extract definitions containing a task, output contract, storage contract, and one-dimensional string array. Create a replacement when the workflow changes, retrieve definitions for inspection, and delete definitions you no longer need.

Endpoints

Automations are immutable reusable browser workflow definitions. Jobs execute saved definitions; create a new automation and delete the old one when its contract or steps change.

POSThttps://api.browserfleet.dev/api/automations

Create Automation

Creates an automation definition.

Create Automation request fields
Field	Location	Type	Required	Description
name	JSON Body	string	Yes	Display name returned with the automation.
task	JSON Body	string	Yes	Task the browser automation should complete.
output	JSON Body	object	Yes	Flat result-data contract mapping each requested source value to boolean, number, or string.
storage	JSON Body	{ name: string, description: string }[]	Yes	Zero or more named files every job created from this automation should store. Use an empty array when no file is requested. Multiple files are packaged into one shared archive.
storage[].name	JSON Body	string	When storage is requested	Unique safe filename returned unchanged in result.storage. Include the extension; only a single variable-format file may use an extensionless name.
storage[].description	JSON Body	string	When storage is requested	Plain-English description of the file every run should preserve.
steps	JSON Body	string[]	Yes	Ordered one-dimensional array of plain-text browser instructions. An exact same-origin in-page fetch function may be supplied after a step establishes that official origin.
steps[]	JSON Body	string	Yes	One browser instruction consumed as part of the same scraper run.
stealthConfiguration	JSON Body	DEFAULT \| STATIC_IP_POOL	No	Browser and network configuration used by every job. Omission selects DEFAULT.
webhookUrl	JSON Body	URL	No	Endpoint that receives one best-effort job.finished POST when a job reaches Done or Error. The request uses the organization's API key as its bearer credential and is not retried.

Example Request

curl -X POST "https://api.browserfleet.dev/api/automations" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Portal dataset export",
    "task": "Use the visible portal UI at %portalUrl to download the complete dataset.",
    "output": {},
    "storage": [
      {
        "name": "dataset.csv",
        "description": "Complete unchanged CSV dataset downloaded through the portal UI"
      }
    ],
    "steps": [
      "Open %portalUrl in the browser.",
      "Use the visible bulk-download or export-all control exactly once as the final browser action."
    ],
    "stealthConfiguration": "DEFAULT",
    "webhookUrl": "https://example.com/webhooks/browser-fleet"
  }'

201 Created

{
  "automationId": "jh7d9...",
  "createdAt": "2026-06-17T10:00:00.000Z",
  "name": "Portal dataset export",
  "task": "Use the visible portal UI at %portalUrl to download the complete dataset.",
  "output": {},
  "storage": [
    {
      "name": "dataset.csv",
      "description": "Complete unchanged CSV dataset downloaded through the portal UI"
    }
  ],
  "steps": [
    "Open %portalUrl in the browser.",
    "Use the visible bulk-download or export-all control exactly once as the final browser action."
  ],
  "stealthConfiguration": "DEFAULT",
  "webhookUrl": "https://example.com/webhooks/browser-fleet"
}

Create Automation response fields
Field	Type	Description
automationId	string	Public id used by automation and job endpoints.
createdAt	string	Creation timestamp as an ISO string.
name, task, output, storage, steps	mixed	Stored automation definition fields.
stealthConfiguration, webhookUrl	string \| null	Stored browser route and terminal webhook configuration. webhookUrl is null when omitted.

Create Automation error responses
Status	Body	Meaning
400	{ "error": "Invalid request body", "issues": { ... } }	The request body is malformed or cannot be validated.
400	{ "error": "Invalid request body", "issues": { ... } }	One or more required automation fields are missing or invalid.
401	{ "error": "Unauthorized" } or { "error": "Invalid API key" }	The request is not authenticated.

GEThttps://api.browserfleet.dev/api/automations?automationId={automationId}

Retrieve Automation

Returns one automation definition.

Retrieve Automation request fields
Field	Location	Type	Required	Description
automationId	Query String	string	Yes	Automation id returned by create automation.

Example Request

curl "https://api.browserfleet.dev/api/automations?automationId=jh7d9..." \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY"

200 OK

{
  "automationId": "jh7d9...",
  "createdAt": "2026-06-17T10:00:00.000Z",
  "name": "Portal dataset export",
  "task": "Use the visible portal UI at %portalUrl to download the complete dataset.",
  "output": {},
  "storage": [
    {
      "name": "dataset.csv",
      "description": "Complete unchanged CSV dataset downloaded through the portal UI"
    }
  ],
  "steps": [
    "Open %portalUrl in the browser.",
    "Use the visible bulk-download or export-all control exactly once as the final browser action."
  ],
  "stealthConfiguration": "DEFAULT",
  "webhookUrl": "https://example.com/webhooks/browser-fleet"
}

Retrieve Automation response fields
Field	Type	Description
automationId	string	Automation id.
createdAt	string	Creation timestamp as an ISO string.
name, task, output, storage, steps	mixed	Stored automation definition fields.
stealthConfiguration, webhookUrl	string \| null	Stored browser route and terminal webhook configuration. webhookUrl is null when omitted.

Retrieve Automation error responses
Status	Body	Meaning
400	{ "error": "Missing automationId" }	The automationId query parameter is empty or absent.
401	{ "error": "Unauthorized" } or { "error": "Invalid API key" }	The request is not authenticated.
404	{ "error": "Automation not found" }	The automation id could not be found.

DELETEhttps://api.browserfleet.dev/api/automations?automationId={automationId}

Delete Automation

Deletes one automation definition. Jobs already created from it are not deleted and remain retrievable and purgeable by jobId.

Delete Automation request fields
Field	Location	Type	Required	Description
automationId	Query String	string	Yes	Automation id returned by create automation.

Example Request

curl -X DELETE "https://api.browserfleet.dev/api/automations?automationId=jh7d9..." \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY"

200 OK

{
  "automationId": "jh7d9...",
  "deleted": true
}

Delete Automation response fields
Field	Type	Description
automationId	string	Deleted automation id.
deleted	boolean	Always true when deletion succeeds.

Delete Automation error responses
Status	Body	Meaning
400	{ "error": "Missing automationId" }	The automationId query parameter is empty or absent.
401	{ "error": "Unauthorized" } or { "error": "Invalid API key" }	The request is not authenticated.
404	{ "error": "Automation not found" }	The automation id could not be found.