Browser setup

Manage the sites allowed to send browser data, and read browser protection coverage and issues.

Browser setup is the API form of Developers → Browser setup in the dashboard. It holds your site list: the only HTTPS sites allowed to send browser data to AbuseZero. It also reports where the browser script is running, how much of your recent traffic arrived with browser data, and the most pressing problem you can fix, if there is one.

Browser protection is always on. For how it works, see Browser protection. To install it, see Set up browser protection. If your site sets a Content Security Policy, copy the sources shown in Developers → Browser setup into it.

Examples on this page use a server client:

import { AbuseZero } from "abusezero/server";

const abusezero = new AbuseZero({ key: process.env.ABUSEZERO_SECRET_KEY!, outage: "throw" });

The browser collection object

{
  "object": "browser_collection",
  "origins": ["https://app.example.com", "https://www.example.com"],
  "revision": 3,
  "sites": [
    {
      "origin": "https://app.example.com",
      "listed": true,
      "first_seen_at": "2026-10-01T09:00:00.000Z",
      "last_seen_at": "2026-10-29T15:42:10.000Z",
      "sdk_version": "0.11.0"
    },
    {
      "origin": "https://www.example.com",
      "listed": true,
      "first_seen_at": null,
      "last_seen_at": null,
      "sdk_version": null
    },
    {
      "origin": "https://staging.example.com",
      "listed": false,
      "first_seen_at": "2026-10-27T10:15:00.000Z",
      "last_seen_at": "2026-10-29T08:03:51.000Z",
      "sdk_version": "0.11.0"
    }
  ],
  "issue": null,
  "issue_since": null,
  "coverage": {
    "days": 7,
    "total": 6210,
    "collected": 5874,
    "consent_declined": 214,
    "not_loaded": 0,
    "blocked": 88,
    "timed_out": 21,
    "failed": 3,
    "site_not_listed": 0,
    "sdk_outdated": 0,
    "expired": 10,
    "not_passed_on": 0,
    "not_sent": 0
  },
  "notices": []
}

Field	Type	Description
`object`	`"browser_collection"`	The object type.
`origins`	array of strings	Your site list. Only these sites can send browser data.
`revision`	integer	The site list's revision. It goes up by one with every change.
`sites`	array of objects	Every listed site, followed by the sites where the browser script has run without being listed.
`sites[].origin`	string	The site.
`sites[].listed`	boolean	Whether the site is in your site list.
`sites[].first_seen_at`	string or `null`	When the browser script first reported from this site. `null` if it never has.
`sites[].last_seen_at`	string or `null`	When the browser script last reported from this site.
`sites[].sdk_version`	string or `null`	The AbuseZero browser SDK version last reported from this site.
`issue`	string or `null`	The most pressing problem you can fix, or `null`. See Issues.
`issue_since`	string or `null`	When the current issue started.
`coverage`	object	How your evaluations from the last 7 days arrived, counted by browser data status. `total` is every evaluation counted.
`notices`	array of strings	Browser families affected by a known condition that reduces browser data on every site: `chrome`, `edge`, `firefox`, `safari`, `samsung`, `opera` or `other`. AbuseZero publishes and clears these notices. They need no action from you.

Browser data status

The same statuses appear on each evaluation as browser_data.

Status	Meaning	Action
`collected`	Browser data arrived with the evaluation.	None.
`consent_declined`	The visitor declined consent, so nothing was collected.	None.
`not_loaded`	Your consent tool kept the browser script from loading, and your server sent `unavailable:not_loaded`.	None.
`blocked`	The browser couldn't reach AbuseZero, for example because an extension, network or Content Security Policy blocked it.	If it's frequent, check your Content Security Policy against Browser setup.
`timed_out`	Collection didn't finish in time.	None.
`failed`	Collection failed in the browser.	None.
`site_not_listed`	The page's site isn't in your site list.	Add the site.
`sdk_outdated`	The page uses a browser SDK version AbuseZero no longer accepts.	Update the browser SDK.
`expired`	The browser data reached the evaluation too late to use.	Send the device token sooner after the browser script returns it.
`not_passed_on`	The browser script collected data, but the evaluation didn't include it.	Send the script's `deviceToken` as `identifiers.device_token`.
`not_sent`	The evaluation carried no device token.	Send `deviceToken` with every evaluation, whatever its status.

Issues

issue reports a problem only when it has a cause you can fix and it persists across your recent traffic. Expected losses, such as declined consent, never count. AbuseZero also emails the workspace's owners and admins when a problem persists.

Issue	Meaning	Fix
`not_passed_on`	The browser script collected data for your claims, but your server sent those evaluations without it. Device and automation protection can't run on them.	Send the value the browser script returns as `identifiers.device_token`.
`site_not_listed`	The browser script is running on a site that isn't in your site list, so it can't collect browser data there.	Add the site to your site list.
`sdk_outdated`	Your pages use a version of the browser SDK that AbuseZero no longer accepts, so evaluations arrive without browser data.	Update to the version shown in Developers → Browser setup.
`script_missing`	The browser script stopped reporting from all of your sites while evaluations keep arriving. A recent release may have removed it.	Check that the script still loads on your pages.

Retrieve browser setup

Method	Path	Scope	Idempotency-Key
`GET`	`/v1/browser-collection`	`browser_collection:read`	Not used

Also available as abusezero browser-collection get in the AbuseZero CLI, abusezero_get_browser_collection on the AbuseZero MCP server and browserCollection() in the AbuseZero Node.js SDK.

Example

const setup = await abusezero.browserCollection();

Response

Returns 200 with the browser collection object.

Update the site list

Replaces your site list. Send every site you want to keep.

Method	Path	Scope	Idempotency-Key
`PATCH`	`/v1/browser-collection`	`browser_collection:write`	Required

Also available as abusezero browser-collection update in the AbuseZero CLI, abusezero_update_browser_collection on the AbuseZero MCP server and updateBrowserCollection() in the AbuseZero Node.js SDK.

Request body

Field	Type	Required	Limits	Description
`origins`	array of strings	Yes	Up to 20 HTTPS URLs, each up to 256 characters	The sites allowed to send browser data. Each URL is saved as its origin: scheme, host and port. Paths are dropped and repeated sites are merged. Send an empty array to remove every site.
`revision`	integer	No		The `revision` you last read. When it's sent and the list has changed since, the update is refused, so you never overwrite someone else's change.

Example

const setup = await abusezero.updateBrowserCollection(
  {
    origins: ["https://app.example.com", "https://www.example.com", "https://staging.example.com"],
    revision: 3,
  },
  "browser-sites-rev-3",
);

Response

Returns 200 with the updated browser collection object. Its revision is one higher.

Errors

Code	Status	Meaning
`ORIGIN_NOT_ALLOWED`	422	A site doesn't use HTTPS.
`INVALID_FIELD`	422	A value isn't a URL, is longer than 256 characters, or there are more than 20.
`REVISION_CONFLICT`	409	The site list changed after you read it. Retrieve it again, reapply your change and retry.

For every other code, see REST API errors.

The browser collection objectCopy Anchor Link

Browser data statusCopy Anchor Link

IssuesCopy Anchor Link

Retrieve browser setupCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

Update the site listCopy Anchor Link

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

ResponseCopy Anchor Link

ErrorsCopy Anchor Link

RelatedCopy Anchor Link

Browser protection

Set up browser protection

AbuseZero browser SDK

On this page

The browser collection object

Browser data status

Issues

Retrieve browser setup

Example

Response

Update the site list

Request body

Example

Response

Errors

Related