API Reference

Automations

Define a reusable browser workflow with a task, ordered steps, output fields, and files. Create, retrieve, update, or delete automations with these endpoints.

Scraper

Each job starts a browser session and gives the scraper the automation's task, steps, variables, output fields, and requested files.

Browser Scraper

AIAny OpenAI-compatible APIThe model you choose

DSOpenCode GoDeepSeek V4.1 Flash

CLClaude-compatible APIsThe model you choose(coming soon)

The scraper uses the website's interface to navigate, fill forms, read results, and download files. It returns the values and files you request. Match and process those results in your own code.

Steps

The task describes the outcome. Steps are an ordered array of plain-text instructions for the browser.

string

Each array item is one plain-text browser instruction.

flat array

Steps are plain strings. Nested arrays and step objects are rejected.

visible labels

Name buttons, links, and fields by their visible labels. Give the exact values to enter.

URLs

The scraper opens only URLs written in the steps. It reaches other pages by clicking the website's own links and controls.

page scripts

A step can include a complete JavaScript function, such as (async () => { ... }), for the scraper to run in the open page exactly as written. The scraper does not write or edit the function.

browser actions only

The scraper uses input values exactly as given. It does not create search variations, match records, filter rows, or interpret downloaded data; do that in your own code.

[
  "Open %portalUrl.",
  "Click the Export CSV button to download the complete dataset."
]

Execution and Order

The scraper receives the full array and follows its steps in order during one browser session.

one run

Every step runs in the same job and browser session, one after another. Steps never run in parallel or as separate jobs.

ordered instructions

Write navigation, form input, and the final download or capture in the order they must happen.

exact controls

Name controls by their visible labels, such as Download full list or Export all, instead of describing a search in general terms.

unchanged files

A file can be a download the website starts, a full-page screenshot, a Markdown copy of the page, or a JSON document opened in the browser, as the steps instruct. Every file is stored exactly as captured, without conversion or editing.

Variables

Use a token such as %portalUrl in the task or steps. Before the job runs, each key in its variables object is replaced with the corresponding value.

%tokenName

The key must match the token exactly, including capitalization and the leading percent sign. Longer keys are replaced first, so %url and %urlPath do not collide.

string values

The public jobs API accepts a string value for every variable key.

references

Tokens are replaced in the task and steps. Storage names and descriptions are used as written.

{
  "automationId": "3f9c2b1e-8a4d-4c6e-9b7a-2d5e8f1a0c34",
  "variables": {
    "%portalUrl": "https://example.com/registry"
  }
}

Output Schema

Output is a flat object that names each value a job returns and its JSON type. Use an empty object when you need only files. List requested files separately in storage.

{}

An automation that only downloads files requests no values, so its output is {}.

named files

List one storage entry for each file you know a job produces, such as a screenshot and an HTML copy of a result page. Mark a file that only one outcome produces as optional.

collections

When the number of files is known only while the job runs, such as one response per results page of a complete list, use one storage entry with a collection. The job stores every matching file unchanged under the collection's prefix and extension.

requested fields

Each key names one value the scraper reads from the website. Request values the website shows, not conclusions that need your own matching logic.

type labels

Each requested field uses the literal type label boolean, number, or string.

exact keys

The data of a Done job contains every requested key and no other keys.

File-only automation:
{}

Requested output values:
{ "productName": "string", "price": "number", "inStock": "boolean" }

Endpoints

An automation defines a reusable browser workflow. Jobs use its saved task, steps, output, and storage settings. Wait for active jobs to finish before changing their output or storage contract.

POSThttps://api.browserfleet.dev/rest/public/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 object mapping each requested value to boolean, number, or string. Use {} when the job only stores files.
storage	JSON Body	object[]	Yes	Zero or more files every job created from this automation stores. Use an empty array when no file is requested. Each file is stored unchanged with its own storage id.
storage[].name	JSON Body	string	When storage is requested	Unique filename of letters, digits, underscores, hyphens, and dots, returned in result.storage. Include the extension. Only a storage array with exactly one file may omit it, for a file whose format is known only when the job runs.
storage[].description	JSON Body	string	When storage is requested	Plain-English description of the file's contents and format.
storage[].extension	JSON Body	string	No	Format the stored file must have, without a leading dot, for example csv. When it is set, a job whose file has another format ends with Error instead of storing it.
storage[].optional	JSON Body	boolean	No	Set to true for a file that only one outcome produces, such as a screenshot of a no-results page. When storage is requested, a Done job stores every required file and at least one file.
storage[].collection	JSON Body	object	No	Stores every raw file of one kind that the job finds, however many there are, such as one response per results page or one file per downloaded document. Each file is stored unchanged as its own object under its own filename, after the job reaches the source's last page or item. A collection is the only entry in storage, it is required, and its file format is set only in collection.extension.
storage[].collection.prefix	JSON Body	string	When collection is set	Beginning of every collected filename, made of letters, digits, underscores, and hyphens, for example results_page.
storage[].collection.extension	JSON Body	string \| string[]	When collection is set	Format of every collected file without a leading dot, for example json, or a list of the distinct formats that a mixed collection's files may have. Each file keeps its own format's extension.
storage[].collection.occurrenceOrdinal	JSON Body	boolean	No	true to name each downloaded file by the order in which the job started its download: the prefix, the download number counted from 1, and the extension, for example results_page_3.csv. It needs a single extension.
storage[].collection.frameDocuments	JSON Body	object	No	Collects pages that open inside a frame of the source page. Each such page whose address begins with frameDocuments.urlPrefix is stored exactly as it arrived, with no second request.
storage[].collection.frameDocuments.urlPrefix	JSON Body	string	When frameDocuments is set	Absolute https address that every collected framed page begins with.
steps	JSON Body	string[]	Yes	Ordered array of plain-text browser instructions.
steps[]	JSON Body	string	Yes	One browser instruction, run in order in the job's browser session.
stealthConfiguration	JSON Body	STEALTH \| STEALTH_STATIC_IP_ROTATING \| WARP \| NONE	No	Browser and network configuration used by every job. STEALTH runs each job on a dedicated stealth browser, one job per browser at a time, for websites whose bot protection refuses the other configurations. STEALTH_STATIC_IP_ROTATING runs each job on a dedicated stealth browser that leaves through a residential US address held for that job alone, a different address for each job, and, when its storage captures page documents (collection.frameDocuments), blocks requests to sites other than the one that urlPrefix names, for websites that block an address after many jobs. WARP, used when the field is omitted, sends browser traffic through a shared proxy network. NONE connects from the address of the server that runs the job, with no proxy. The names DEFAULT and DIRECT are accepted and stored as WARP and NONE.
webhookUrl	JSON Body	URL	No	Endpoint that receives one job.finished POST when a job reaches Done or Error. The JSON body is { "event": "job.finished", "job": { ... } }, where job holds jobId, automationId, status, priority, variables, metadata, result, error, createdAt, runStartAt, runEndAt, and updatedAt. The request sends your organization's API key as its bearer token, times out after 10 seconds, and is not retried, so poll the job if a delivery fails.
maxConcurrency	JSON Body	integer	No	Most jobs of this automation that run at once, 1 or more. Further jobs stay Pending until a running job ends. Omit it for no limit.

Example 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"
  }'

201 Created 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
}

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, maxConcurrency	string \| integer \| null	Stored browser configuration, webhook endpoint, and concurrency limit. webhookUrl and maxConcurrency are null when omitted.

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

GEThttps://api.browserfleet.dev/rest/public/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)

curl "https://api.browserfleet.dev/rest/public/automations?automationId=3f9c2b1e-8a4d-4c6e-9b7a-2d5e8f1a0c34" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY"

200 OK 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
}

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, maxConcurrency	string \| integer \| null	Stored browser configuration, webhook endpoint, and concurrency limit. webhookUrl and maxConcurrency are null when omitted.

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

PATCHhttps://api.browserfleet.dev/rest/public/automations

Update Automation

Changes the fields the body sends and keeps every other field. Each sent field follows the same rules as on create. Jobs that start after the update run the new definition. A running job's result is checked against the automation's current output and storage, so change those two fields only while no job of the automation is In Progress.

Update Automation request fields
Field	Location	Type	Required	Description
automationId	JSON Body	string	Yes	Automation id returned by create automation.
name, task, output, storage, steps, stealthConfiguration	JSON Body	mixed	No	Replacement values with the same shapes as on create. A sent storage or steps array replaces the whole stored array.
webhookUrl	JSON Body	URL \| null	No	New webhook endpoint, or null to remove the webhook.
maxConcurrency	JSON Body	integer \| null	No	New concurrency limit of 1 or more, or null to remove the limit.

Example Request (cURL)

curl -X PATCH "https://api.browserfleet.dev/rest/public/automations" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "automationId": "3f9c2b1e-8a4d-4c6e-9b7a-2d5e8f1a0c34",
    "maxConcurrency": 2
  }'

200 OK 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": 2
}

Update 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 after the update.
stealthConfiguration, webhookUrl, maxConcurrency	string \| integer \| null	Stored browser configuration, webhook endpoint, and concurrency limit after the update.

Update Automation error responses
Status	Body	Meaning
400	{ "error": "Invalid or missing JSON body" }	The request body is missing or is not valid JSON.
400	{ "error": "Invalid request body", "issues": { ... } }	The automationId is missing, a sent field is invalid, or the body has a field that update does not accept.
401	{ "error": "Invalid API key" }	The API key is missing or invalid.
404	{ "error": "Automation not found" }	The automation id could not be found.

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

Delete Automation

Deletes one automation definition. Jobs already created from it are not deleted and remain retrievable 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)

curl -X DELETE "https://api.browserfleet.dev/rest/public/automations?automationId=3f9c2b1e-8a4d-4c6e-9b7a-2d5e8f1a0c34" \
  -H "Authorization: Bearer $BROWSER_FLEET_API_KEY"

200 OK Response (JSON)

{
  "automationId": "3f9c2b1e-8a4d-4c6e-9b7a-2d5e8f1a0c34",
  "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": "Invalid API key" }	The API key is missing or invalid.
404	{ "error": "Automation not found" }	The automation id could not be found.