/function API

info

Currently, Browserless V2 is available in production via two domains: production-sfo.browserless.io and production-lon.browserless.io

A quick way to run commands with Browserless is via our /function API. You can use Python, NodeJS or any other language that supports making HTTP requests, so you don't need to install any libraries on your end.

The /function endpoint allows for POSTing of custom code and context to run them with. The code function, which only supports puppeteer code, gets called with an object containing several properties: a page property, which is a puppeteer page object, and context which is the context you provide in the JSON body.

Functions should return an object with two properties: data and type. data can be whatever you'd like (Buffer, JSON, or plain text) and type is a string describing the content-type of data. Browserless reads both of these from your functions return value and resolves the request appropriately.

You can check the full Open API schema here.

Basic Usage

Both the /function and the /download API environments use Ecmascript modules. You can use any code and native APIs available in the Chrome browser environment.

JS Code

export default async function ({ page }) {
  const rndNumber = () => {
    return Math.floor(Math.random() * (10**6 - 0));
  };

  await page.goto("https://example.com/");
  const url = await page.title();
  const numbers = [...Array(5)].map(() => rndNumber());

  return {
    data: {
      url,
      numbers,
    },
    // Make sure to match the appropriate content here
    type: "application/json",
  };
}

cURL Request

curl -X POST \
  https://production-sfo.browserless.io/function?token=YOUR-API-TOKEN \
  -H 'Content-Type: application/javascript' \
  -d 'export default async function ({ page }) {
  const rndNumber = () => {
    return Math.floor(Math.random() * (10**6 - 0));
  };

  await page.goto("https://example.com/");
  const url = await page.title();
  const numbers = [...Array(5)].map(() => rndNumber());

  return {
    data: {
      url,
      numbers,
    },
    // Make sure to match the appropriate content here
    type: "application/json",
  };
}'

Example Reponse

{
  "data": {
    "url": "Example Domain",
    "numbers": [
      854246,
      114512,
      212580,
      482122,
      107878
    ]
  },
  "type": "application/json"
}

Importing libraries

Since the /function API uses ESM modules, you can use import syntax over HTTP to load moules. For instance, let's try leading the Fake module.

JS Code

import { faker } from "https://esm.sh/@faker-js/faker";

export default async function () {
  const Internet = faker.internet;
  const rndData = [...Array(5)].map(() => ({
    domain: Internet.domainName(),
    ip: Internet.ip(),
    mac: Internet.mac(),
    protocol: Internet.protocol(),
  }));

  return {
    data: { domains: rndData },
    type: "application/json",
  };
}

cURL Request

curl -X POST \
  https://production-sfo.browserless.io/download?token=YOUR-API-TOKEN \
  -H 'Content-Type: application/javascript' \
  -d 'import { faker } from "https://esm.sh/@faker-js/faker";

export default async function () {
  const Internet = faker.internet;
  const rndData = [...Array(5)].map(() => ({
    domain: Internet.domainName(),
    ip: Internet.ip(),
    mac: Internet.mac(),
    protocol: Internet.protocol(),
  }));

  return {
    data: { domains: rndData },
    type: "application/json",
  };
}'

JSON API

You can also use the /function API sending a JSON payload. You must send an object with the following values:

• code: String, required — custom function code.
• context: Object, optional — value used to pass context values and arguments to the code

Example

JS Code

import { faker } from "https://esm.sh/@faker-js/faker";

export default async function ({ context }) {
  const Internet = faker.internet;
  const rndData = [...Array(context.len)].map(() => ({
    domain: Internet.domainName(),
    ip: Internet.ip(),
    mac: Internet.mac(),
    protocol: Internet.protocol(),
  }));

  return {
    data: {
      domains: rndData,
      length: context.len
    },
    type: "application/json",
  };
}

cURL request

curl --request POST \
  --url 'http://chrome-dev.browserless.io/chrome/download' \
  --header 'Content-Type: application/json' \
  # Minified code
  --data '{
  "code": "import{faker as a}from\"https://esm.sh/@faker-js/faker\";export default async function({context:o}){let t=a.internet,e=[...Array(o.len)].map(()=>({domain:t.domainName(),ip:t.ip(),mac:t.mac(),protocol:t.protocol()}));return{data:{domains:e,length:o.len},type:`application/json`}};",
  "context": {
    "len": 10
  }
}'