REST and gRPC endpoints for programmatic access to Bridge Kernel runtime, ledger, and metrics.

API Reference

Bridge Kernel exposes a local API for programmatic access to the runtime, ledger, metrics, and policy management. The API is available when Bridge Kernel runs in daemon mode.

Base URL

http://localhost:9100/api/v1

The port is configurable via api.port in bridge.yaml or the BRIDGE_API_PORT environment variable.

Authentication

Local API requests are authenticated via bearer token:

curl -H "Authorization: Bearer $BRIDGE_API_TOKEN" http://localhost:9100/api/v1/status

Endpoints

Runtime

`GET /api/v1/status`

Returns runtime health and configuration summary.

{
  "node_id": "bridge-node-local",
  "environment": "production",
  "key_provider": "tpm",
  "ledger_events": 1542,
  "ledger_unsynced": 12,
  "status": "ok",
  "degraded_reasons": [],
  "last_heartbeat": "2026-03-08T14:22:01Z"
}

`GET /api/v1/metrics`

Returns current RuntimeMetricsSnapshot.

{
  "ingest_attempted": 2500,
  "ingest_accepted": 2480,
  "ingest_rejected_replay": 12,
  "ingest_rejected_policy": 8,
  "sync_published": 1200,
  "sync_received": 980,
  "queue_peak": 42,
  "last_updated": "2026-03-08T14:22:01Z"
}

Ledger

`GET /api/v1/ledger/summary`

Returns ledger event counts.

{
  "total_events": 1542,
  "unsynced_events": 12
}

`GET /api/v1/ledger/events?limit=10&offset=0&unsynced=false`

Returns paginated ledger events with proof envelopes.

`GET /api/v1/ledger/events/:event_id`

Returns a single event by ID with its full ProofEnvelope.

Ingest

`POST /api/v1/ingest`

Submit an event for ingestion programmatically.

{
  "sector": "power",
  "event_type": "meter_reading",
  "source": "api-client-01",
  "payload": {
    "voltage_v": 230.5,
    "current_a": 12.4,
    "power_kw": 3.1
  }
}

Response:

{
  "event_id": "evt-4d83bf2c...",
  "proof_hash": "4fd0a00f...",
  "status": "accepted"
}

Policy

`GET /api/v1/policy/active`

Returns the current active policy bundle.

`POST /api/v1/policy/stage`

Stage a new policy bundle (requires signed bundle in request body).

`POST /api/v1/policy/promote`

Promote the staged bundle to active.

`POST /api/v1/policy/rollback`

Rollback to the previous active bundle.

Sync

`GET /api/v1/sync/status`

Returns peer sync state and watermarks.

`POST /api/v1/sync/trigger`

Trigger an immediate sync cycle.

Error responses

All errors follow a consistent format:

{
  "error": "replay_rejected",
  "message": "Event timestamp outside replay window",
  "detail": {
    "event_timestamp": "2026-03-08T14:00:00Z",
    "window_start": "2026-03-08T14:12:00Z"
  }
}

Rate limits

API rate limits are configurable per endpoint:

api:
  port: 9100
  rate_limit:
    ingest: 600   # requests per minute
    query: 1200   # requests per minute

API Reference

On this page