API 1.0

Browserbear API Reference

Browserbear is a browser automation service.

  1. You design a browser automation in Browserbear
  2. We turn it into an API
  3. You use the API to run the automation and get the output
Base URL
https://api.browserbear.com

Authentication

Browserbear uses API keys to allow access to the API.

Browserbear expects the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer API_KEY

You can find your workspace API Keys in API Keys ↗.

All API requests on Browserbear are scoped to a Workspace.

Endpoint
get/v2/auth
Sample Response
{
  "message": "Authorized",
  "workspace": "My Workspace"
}

Account

To check your account status at any time you can use this endpoint. It will respond with your quota levels and current usage levels. Usage resets at the start of every month.

Endpoint
get/v1/account
Sample Response
{
  "created_at": "2022-12-01T03:48:23.228Z",
  "uid": "x4p71qmnY1nD5obLdG",
  "plan_name": "Browserbear Automate",
  "api_usage": 28,
  "api_quota": 36000
}

Errors

The Browserbear API uses the following status / error codes. The Browserbear API rate limit is 30 requests per 10 seconds.

202Accepted -- Your request is has been accepted for processing
200OK
400Bad Request -- Your request is invalid.
401Unauthorized -- Your API key is wrong.
402Payment Required -- Your have run out of quota.
404Not Found -- The specified request could not be found.
429Too Many Requests -- Slow down!
500Internal Server Error -- We had a problem with our server. Try again later.
503Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Async

The Browserbear API is asynchronous. When creating a new run, you POST a request, the API responds immediately with 202 Accepted and you either receive the generated result via webhook or via polling.

You can run as many concurrent tasks as you want, as long as you request them within the API rate limit.

Tasks

A Task is a set of instructions that make up a browser automation. Tasks are created and edited via the Browserbear dashboard. The API can be used to list and retrieve Tasks.

To execute a Task, create a run.

Endpoints
get/v1/tasks/:uid
get/v1/tasks

The task object

Attributes

  • uid stringThe unique ID for this object.
  • name stringThe name of this task.
  • viewport_width integerStarting viewport width.
  • viewport_height integerStarting viewport height.
  • steps arrayArray of steps that make up this task.
Sample Object
{
  "created_at": "2022-12-01T03:48:43.728Z",
  "name": "Elon Screenshot",
  "uid": "851LyQMwvZw2lrXKpq",
  "viewport_width": 1024,
  "viewport_height": 768,
  "steps": [
    {
      "action": "go",
      "config": {
        "url": "https://twitter.com/elonmusk"
      },
      "uid": "GNqV2ngBmly7O9dPRe"
    },
    {
      "action": "take_screenshot",
      "uid": "Km0k2XNbnlBA6Pplde"
    }
  ]
}

Retrieve a task

Parameters

  • uid stringrequiredThe task uid that you want to retrieve.
get/v1/tasks/:uid
Sample Request
fetch(`https://api.browserbear.com/v1/tasks/${UID}`, {
  method: 'GET',
  headers: {
    'Authorization' : `Bearer ${API_KEY}`
  }
})

List all tasks

Parameters

  • page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get/v1/tasks
Sample Request
fetch(`https://api.browserbear.com/v1/tasks`, {
  method: 'GET',
  headers: {
    'Authorization' : `Bearer ${API_KEY}`
  }
})

Runs

A Run is an execution of a task. You can start a new Run via API.

Runs execute asynchronously. When you make a new POST request you will receive a 202 Accepted response. The Run will then begin to execute.

To get the status of a Run you can query the GET endpoint.

To be notified when a Run finishes you can use a webhook.

Endpoints
post/v1/tasks/:task_uid/runs
get/v1/tasks/:task_uid/runs/:uid
get/v1/tasks/:task_uid/runs

The run object

Attributes

  • uid stringThe unique ID for this object.
  • task stringThe uid of the parent task.
  • video_url stringLink to a video of the task running.
  • outputs arrayArray of data outputs from steps, if any
  • steps arrayArray of task steps at the time of this run.
Sample Object
{
  "created_at": "2022-12-06T04:34:15.238Z",
  "video_url": "https://media.browserbear.com/videos/oZwrg1DnX5qQM0v7Wq/2843a2b0a90c09b80d6d81f037854b5a3f33f2fa.mp4",
  "uid": "5dDvA47kyWQ2N61w3R",
  "task": "851LyQMwvZw2lrXKpq",
  "steps": [
    {
      "action": "go",
      "config": {
        "url": "https://twitter.com/elonmusk"
      },
      "uid": "GNqV2ngBmly7O9dPRe"
    },
    {
      "action": "take_screenshot",
      "uid": "Km0k2XNbnlBA6Pplde",
      "output": "https://media.browserbear.com/screenshots/oZwrg1DnX5qQM0v7Wq/o2Wm9xgbkrEzpqDZ0Y/1.jpg"
    }
  ],
  "status": "finished",
  "finished_in_seconds": 6,
  "webhook_url": null,
  "outputs": [],
  "metadata": null
}

Create a run

Parameters

  • steps arrayArray of step overrides. You must include the uid, action and a config object for each step you want to modify. If you don't add any overrides the step will run according to its default config. Set skip:true if you want to skip a step for this run.
  • webhook_url stringA url to POST the full Run object to upon finishing.
  • metadata stringAny metadata you need to store e.g. ID of a record in your DB.
post/v1/tasks/:task_uid/runs
Sample Request
//go to a different url
var data = {
  "steps": [
    {
      "uid": "GNqV2ngBmly7O9dPRe",
      "action": "go",
      "config": {
        "url": "https://twitter.com/apple"
      }
    }
  ]
}
fetch('https://api.browserbear.com/v1/tasks/:task_uid/runs', {
  method: 'POST',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'Authorization' : `Bearer ${API_KEY}`
  }
})

Retrieve a run

Parameters

  • task_uid stringrequiredThe task uid.
  • uid stringrequiredThe run uid that you want to retrieve.
get/v1/tasks/:task_uid/runs/:uid
Sample Request
fetch(`https://api.browserbear.com/v1/tasks/${TASK_UID}/runs/${UID}`, {
  method: 'GET',
  headers: {
    'Authorization' : `Bearer ${API_KEY}`
  }
})

List all runs

Parameters

  • task_uid stringrequiredThe task uid.
  • page integerquery stringThe page of results you would like to retrieve. The API returns 25 items per page.
get/v1/tasks/:task_uid/runs
Sample Request
fetch(`https://api.browserbear.com/v1/tasks/${TASK_UID}/runs`, {
  method: 'GET',
  headers: {
    'Authorization' : `Bearer ${API_KEY}`
  }
})

Feeds

A Feed is a custom json feed of data from a task run.

You set up Feeds in the Browserbear dashboard.

Feeds are different from Run outputs in that you can apply transformations to massage the data, if needed.

The feeds endpoint lists all custom feeds in a workspace.

Endpoints
get/v1/feeds

The feed object

Attributes

  • uid stringThe unique ID for this object.
  • name stringThe name of this feed.
  • name stringThe description of this feed.
  • last_run_at datetimeTimestamp of when this feed was last updated.
  • url stringThe URL to the custom feed.
Sample Object
{
  "name": "Bannerbear.com",
  "uid": "X52gd36yKgye0Za1Ao",
  "description": "Scraping the Bannerbear blog",
  "last_run_at": "2023-09-14T06:39:24.036Z",
  "url": "http://api.browserbear.com/v1/tasks/bJZvOg2nY9nxP9yrzD/feeds/X52gd36yKgye0Za1Ao"
}

List all feeds

Parameters

  • No parameters
get/v1/feeds
Sample Request
fetch(`https://api.browserbear.com/v1/feeds`, {
  method: 'GET',
  headers: {
    'Authorization' : `Bearer ${API_KEY}`
  }
})