HTTP API

Base path default: /__idebug. Implemented by createIdebugHandler in @idebug/core.

All JSON responses use Content-Type: application/json; charset=utf-8.

Every request under the base path is security-gated first (see Security posture).

Method	Path	Response
`GET`	`/__idebug` or `/__idebug/`	SPA `index.html`, or 503 if UI assets missing
`GET`	`/__idebug/assets/*`	Static files from `@idebug/ui` dist
`GET`	`/__idebug/api/health`	`{ ok, version, appName, time, security }`
`GET`	`/__idebug/api/sessions`	`{ sessions: SessionSummary[] }` newest first
`GET`	`/__idebug/api/sessions/:id`	`{ session, events }` or 404
`GET`	`/__idebug/api/events?sinceSequence=&limit=`	`{ events }` (limit default 100, max 1000)
`GET`	`/__idebug/api/stream`	SSE `data: <TraceEvent JSON>` + heartbeats
`DELETE`	`/__idebug/api/sessions`	Clear store → `{ ok: true }`

Security gate (all paths)

Failure	Status	`reason`
Host not localhost/loopback (and not in `allowedHosts`)	403	`host_not_allowed`
Peer address not loopback (`localRemoteOnly`)	403	`remote_not_local`
Missing access token when configured	401	`token_missing`
Wrong access token	401	`token_invalid`

Token accepted via:

Authorization: Bearer <token>
X-IDebug-Token: <token>
?idebug_token=<token> (required for EventSource / SSE)

Response headers include X-Frame-Options: DENY, Cache-Control: no-store, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer.

Notes

No multi-user auth — optional shared accessToken only; same-origin local debugger.
Unknown /api/* → 404 JSON.
Non-API GET under base path falls back to SPA for client-side routes.
If staticDir has no index.html, API routes still work (SPA may 503).

Example

# Defaults: loopback Host + peer; open http://127.0.0.1:3001/__idebug
curl -s http://127.0.0.1:3001/__idebug/api/health
curl -s http://127.0.0.1:3001/__idebug/api/sessions | jq .
 
# With accessToken configured:
curl -s -H "Authorization: Bearer $IDEBUG_TOKEN" \
  http://127.0.0.1:3001/__idebug/api/health
curl -s "http://127.0.0.1:3001/__idebug/api/sessions?idebug_token=$IDEBUG_TOKEN" | jq .

Database queries Event payloads