API Reference

The API server runs on http://127.0.0.1:4217 by default, configurable via the PORT environment variable.

GET /api/health

Health check endpoint.

curl http://127.0.0.1:4217/api/health

Response:

{
  "ok": true,
  "service": "safe-examine-browser"
}

GET /api/browsers

List detected browsers on the system. Optionally pass a custom executable path.

curl http://127.0.0.1:4217/api/browsers
curl "http://127.0.0.1:4217/api/browsers?customPath=C:/custom/browser.exe"

Response: array of BrowserTarget objects

[
  {
    "id": "chromium",
    "name": "Bundled Chromium",
    "capability": "native",
    "installed": true,
    "executablePath": "...",
    "notes": "Bundled by Playwright."
  }
]

POST /api/examine

Execute a URL examination across selected browsers.

curl -X POST http://127.0.0.1:4217/api/examine \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "browsers": ["chromium", "firefox"],
    "policy": "strict"
  }'

Field	Type	Description
url	string	Target URL (http or https)
browsers	string[]	Browser IDs to run
policy	string	Safety preset: strict, balanced, or diagnostic
customExecutablePath	string (optional)	Custom Chromium executable path

Response: MatrixReport (see Report Format)

GET /api/runs

List run IDs sorted by most recent first.

curl http://127.0.0.1:4217/api/runs

GET /api/runs/:runId/report

Retrieve the JSON report for a specific run.

curl http://127.0.0.1:4217/api/runs/abc123/report

GET /api/runs/:runId/export/html

Retrieve the HTML summary page for a run.

curl http://127.0.0.1:4217/api/runs/abc123/export/html

GET /api/runs/:runId/artifact/*

Serve run artifacts (screenshots, browser reports).

curl http://127.0.0.1:4217/api/runs/abc123/artifact/chromium/chromium-desktop.png