Basic Safety Guard API Quick Start

This quick start reads a site’s PPE compliance figures from a Basic Safety Guard box. You need curl and about ten minutes. The numbers in the answers below are sample values.

Before You Start

Ask an admin of the box to create an API account on the dashboard (API accounts page) with:

• the role Viewer on the site you want to read;
• the scope read (add export to download the log as a file);
• an expiry date.

They give you the token (<API_KEY> below), the box’s address (<BOX_HOST>) and a copy of the box’s certificate (box.pem, from Download the box’s certificate on the API accounts page) with its SHA-256 fingerprint: check it as The Box’s Certificate shows. Authentication and Scopes explains each of these.

Find Your Site

curl --cacert box.pem \
  -H "Authorization: Bearer <API_KEY>" \
  "https://<BOX_HOST>/api/v1/sites"

{
  "items": [
    {
      "id": 1,
      "name": "North Plant",
      "timezone": "Asia/Jakarta",
      "created": "2026-10-01T02:00:00Z",
      "version": 4,
      "my_role": "viewer",
      "location": { "lat": -6.2, "lon": 106.8 },
      "area": null,
      "zones": 3
    }
  ]
}

The answer lists only the sites your account has a role on. Keep the site’s id (here 1).

Read The Compliance Overview

Ask for one period with from and to (RFC 3339; %2B is the + of the time zone offset):

curl --cacert box.pem \
  -H "Authorization: Bearer <API_KEY>" \
  "https://<BOX_HOST>/api/bsg/v1/sites/1/overview?from=2026-11-01T00:00:00%2B07:00&to=2026-11-02T00:00:00%2B07:00"

{
  "index": 91.4,
  "assessed_minutes": 5220,
  "exposure_minutes": 5710,
  "items": { "hard_hat": 96.2, "vest": 93.8, "boots": null, "gloves": null, "goggles": null },
  "violations": 17,
  "hazard_entries": 2,
  "on_site": { "people": 34, "flagged": 1 },
  "target": 95,
  "bands": { "red": 80, "green": 95 },
  "required_items": ["hard_hat", "vest"],
  "unique_people": { "period": 52, "now": 9 }
}

For the same figures per hour or day, call GET /api/bsg/v1/sites/1/trend; per PPE area, GET /api/bsg/v1/sites/1/areas. For the unique people per hour, call GET /api/bsg/v1/sites/1/people with the same from and to.

Read The Detection Log

curl --cacert box.pem \
  -H "Authorization: Bearer <API_KEY>" \
  "https://<BOX_HOST>/api/bsg/v1/sites/1/logs?from=2026-11-01T00:00:00%2B07:00&to=2026-11-02T00:00:00%2B07:00&limit=50"

{
  "named": false,
  "next_before": "2026-11-02T01:12:40Z",
  "items": [
    {
      "track": "11:4821",
      "camera_id": 11,
      "first": "2026-11-02T01:14:05Z",
      "last": "2026-11-02T01:15:32Z",
      "areas": ["Loading Bay"],
      "items": { "hard_hat": 100, "vest": 38.5, "boots": null, "gloves": null, "goggles": null },
      "index": 69.2,
      "violations": 1,
      "person": null,
      "evidence": null
    }
  ]
}

Each row is one person seen by one camera. Without the personal_data scope the log is the anonymous form: named is false, and person and evidence are null. For the next page, send next_before as before.

To download the period as a file, call GET /api/bsg/v1/sites/1/logs/export?format=csv with the scope export.

Next Steps

• Open violations arrive as alerts: GET /api/v1/alerts?site=1&state=open.
• Push them to your system instead of polling: Webhooks (event types bsg.violation and bsg.hazard_entry, and periodic summaries of these figures).
• Every operation and field: Basic Safety Guard API reference and platform API reference.