project-nomad/docs/emergency/LOCAL_API.md

Emergency Local API

Purpose

This API exists to expose the emergency runtime to a local PWA over loopback only.

The API is not public and should not be exposed on the internet.

Base URL

http://127.0.0.1:4187/api/v1

Core model

• Read operations are local-first.
• Base network policy is ON or OFF.
• One-shot sync is an explicit bounded exception path.

Key endpoints

GET /status

Returns high-level runtime state.

Example:

{
  "network_policy": "OFF",
  "network": {
    "reachable": null,
    "last_checked_at": "2026-03-24T18:20:00Z",
    "probe_allowed": false
  },
  "oneshot": {
    "armed": true,
    "state": "armed",
    "scope": "manifests",
    "timeout_seconds": 600,
    "enforce_byte_cap": false,
    "byte_cap_mb": 0,
    "enforce_download_cap": false,
    "download_cap_count": 0,
    "armed_at": "2026-03-24T18:30:00Z",
    "expires_at": "2026-03-24T18:40:00Z"
  },
  "sync": {
    "state": "idle",
    "last_success_at": "2026-03-24T18:20:00Z"
  }
}

GET /mode

Returns base network policy and one-shot state.

PUT /mode

Sets base network policy.

Request:

{
  "network_policy": "OFF"
}

Allowed values:

• ON
• OFF

POST /sync/oneshot

Triggers or arms a bounded one-shot sync while leaving base policy unchanged.

Request:

{
  "scope": "manifests",
  "reason": "manual",
  "arm_if_offline": true,
  "timeout_seconds": 600,
  "enforce_byte_cap": false,
  "byte_cap_mb": 0,
  "enforce_download_cap": false,
  "download_cap_count": 0
}

Behavior:

• if network is available now, queue one short sync job
• if network is unavailable and arm_if_offline = true, keep the request armed until timeout
• auto-disarm after one attempt, success, failure, or timeout

POST /sync/run

Triggers a normal sync cycle. This route is intended for policy ON.

GET /search

Returns local search results only.

GET /documents/:document_id

Returns locally stored document content and provenance metadata.

Notes

• network.reachable may be null when active probing is suppressed by OFF.
• One-shot is the preferred explicit exception path from OFF.
• Cap fields are present in v1 but disabled by default until payload sizes are better understood.