Bermward

API

The read API lets you pull domains, findings, monitors and incidents into your own tools, and manage uptime monitors from code.

Creating a token

Admins create tokens under Settings, API. Give each token a name (2 to 80 characters) so you can tell them apart. The secret starts with sp_ and is shown once, so copy it straight away. Only a hash is stored. Revoke a token at any time; it stops working immediately. The list shows when each token was last used. Creating and revoking tokens is written to the audit log.

Authentication

Request
curl https://YOUR-HOST/api/v1/findings \
  -H "Authorization: Bearer sp_xxxxxxxx"
StatusMeaning
401The header is missing, does not start with sp_, or the token is unknown or revoked.
402The workspace's plan does not include the API.
403The workspace is suspended.
429More than 120 requests in a minute. Wait and retry.

What a token can see

A token acts for the workspace that created it. On a client workspace it sees that client. On an MSP workspace it sees the MSP and every client under it, and each item says which workspace it belongs to with organizationId.

Reading data

MethodPathRoleWhat it does
GET/api/v1/domainstokenUp to 500 domains: id, domain, kind, verified, last scan time and status.
GET/api/v1/findingstokenUp to 200 findings, newest activity first. Open only unless status=all.
GET/api/v1/monitorstokenUp to 500 monitors: id, name, type, target, state, paused.
GET/api/v1/incidentstokenUp to 200 incidents. Open only unless status=all.
GET /api/v1/findings response
{
  "findings": [
    {
      "id": "…",
      "organizationId": "…",
      "domain": "example.com",
      "type": "…",
      "severity": "high",
      "status": "open",
      "title": "…",
      "asset": "…",
      "firstSeenAt": "2026-11-01T09:12:00.000Z",
      "lastSeenAt": "2026-11-18T03:00:00.000Z"
    }
  ]
}

Managing monitors and incidents

MethodPathRoleWhat it does
POST/api/v1/monitorstokenCreate a monitor. Optional organizationId picks a client on an MSP token. Respects monitor limits and the fastest interval of the plan.
PATCH/api/v1/monitors/:idtokenChange fields. The body is merged over the current monitor.
DELETE/api/v1/monitors/:idtokenDelete a monitor.
POST/api/v1/incidents/:id/acknowledgetokenAcknowledge an open incident.
POST/api/v1/incidents/:id/resolvetokenResolve an incident.

Monitor bodies use the same fields as the app: name, type, target, interval, timeout, regions and assertions. See Uptime for the types and options.

The app API

Each page of these docs lists the routes the app itself uses under /api/orgs/:orgId. Those routes use a signed-in session, not API tokens, and can change with the app. For integrations, prefer the token API above and webhooks.

Token management routes

MethodPathRoleWhat it does
GET/api/orgs/:orgId/api-tokensadminList tokens and whether the plan allows them.
POST/api/orgs/:orgId/api-tokensadminBody: name. Returns the token and its secret once.
DELETE/api/orgs/:orgId/api-tokens/:tokenIdadminRevoke.