Your compliance data, in the tools you already run

Scan results should not live in one screen. The CYBERWHITE read-only API lets your PSA or reporting tool pull each client's Essential Eight and SMB1001 results, and the gaps that need work.

Read-only

A key can read. It cannot change a tenant, run a scan or deploy a fix. No write endpoint exists.

The same numbers as the screens

The API returns the same results the app shows, including attested answers and accepted risks.

Described in OpenAPI 3.1

Import the file into your tooling. The file is tested against the API before every release.

Quick start

  1. 1. Create a key

    The account Owner signs in, opens Settings, then Security Settings, then API keys. Name the key after the tool that will use it. The key is shown once, so copy it straight away.

  2. 2. Test the connection

    Send the key in the Authorization header. Never put it in the URL.

    curl https://cyberwhite.ai/api/v1/me \
      -H "Authorization: Bearer cw_live_your_key_here"
  3. 3. Read the gaps for a client

    curl https://cyberwhite.ai/api/v1/clients \
      -H "Authorization: Bearer cw_live_your_key_here"
    
    curl "https://cyberwhite.ai/api/v1/clients/{clientId}/gaps?framework=essential8-ml1" \
      -H "Authorization: Bearer cw_live_your_key_here"

    Each gap looks like this:

    {
      "controlId": "ML1-PO-02",
      "name": "OS patches - workstations (1 month)",
      "status": "non_compliant",
      "detail": "1 of 2 enrolled device(s) are more than 30 days behind on Windows cumulative updates: LAPTOP-07.",
      "source": "scan",
      "riskAccepted": false,
      "riskAcceptedAt": null,
      "priorityScore": null,
      "framework": "essential8-ml1",
      "level": "ML1",
      "lastScannedAt": "2026-10-01T02:14:09Z"
    }

Endpoints

Base address: https://cyberwhite.ai/api/v1

GET /meTests the connection. Returns the key name, its expiry and its limits.
GET /clientsYour clients: id, name, industry, connected, last scanned.
GET /clients/{clientId}One client.
GET /clients/{clientId}/assessmentsThe latest result for each framework and level: score and counts.
GET /clients/{clientId}/assessments/{framework}Control by control. Filter with level and status.
GET /clients/{clientId}/gapsOnly the controls that need work, highest priority first. Poll this to raise tickets.
GET /healthIs the API up? No key needed.

Lists are paged with limit (default 25, maximum 100) and offset. Each list returns the total and a link to the next page.

What each status means

compliant
Proven by the scan, or attested by a person.
partial
A proven gap: some evidence, not enough.
non_compliant
A proven gap.
needs_review
The scan could not prove it either way. Not a gap, not a pass.
licence_required
The tenant lacks the Microsoft licence the check needs.

An accepted risk does not change a status. The gap stays listed, with riskAccepted: true.

Errors

Every error has the same shape: type, title, status, detail and a requestId to quote to support.

400
The request is malformed, for example a key in the URL or a limit above the maximum.
401
The key is missing, not recognised, revoked or expired.
403
API access is not enabled for the account.
404
Not found, or not one of your clients. The API does not say which.
429
Too many requests. Wait for the number of seconds in the Retry-After header.

Limits

  • 60 requests a minute and 10,000 a day for each key.
  • Every response says how many requests are left in the RateLimit-Remaining header.
  • Up to 5 active keys for an account. Each key expires after 12 months.
  • Polling once an hour for each client is plenty. Scan results change when someone scans or answers a control.

What it does not do

  • It does not push. There are no webhooks in version 1, so your tool asks on a schedule.
  • It does not return scan history. It returns the latest result for each framework.
  • It does not return raw Microsoft Graph data, tokens or evidence files.
  • It only sees computers and policies the scan can see. A needs_review control is unverified, not a pass.

Keeping a key safe

  • One key for each tool. If a tool is retired or compromised, revoke its key and leave the others running.
  • Store keys in a password manager or your tool's secret store. Not in email, chat or a ticket.
  • CYBERWHITE stores only a scrambled copy of each key and cannot show it again. If a key is lost, revoke it and create another.
  • Every request is logged against the key that made it.

Who can use it

Read-only API access is included for Founding Program accounts. Advanced API features are not included.

The Founding Program closes 31 December 2026. Join before 31 December 2026 and your plan price stays fixed for as long as you stay subscribed. New core platform capabilities released before 31 December 2027 are included. From 1 January 2027 they are paid add-ons for new customers. See what founding members get

Changes to the API

The address carries the version. Within version 1 we only add: new fields and new endpoints. We do not remove or rename a field. A change that would break your integration ships as a new version, with notice, and version 1 keeps working alongside it.