Local API reference

The API documented here is the local API used by the Diffgazer web app. It is not a hosted public API and it is not meant to be deployed as a standalone internet service.

In web mode, the diffgazer CLI starts the embedded server, serves the browser app, and keeps both on the same localhost origin. DIFFGAZER_SHUTDOWN_TOKEN enables the API gate in every mode. Packaged runs require the x-diffgazer-shutdown-token header for API access outside health checks and preflight requests.

Health responses are lightweight and do not require repository trust.

POST /api/config/actions is the only configuration write route. It accepts the six generic configuration actions as a discriminated union on action, requires repository trust, and rejects bodies over the shared request size limit. Every response is a client-safe summary: configuration identity, readiness, notices, remediation, and available actions. Literal secrets, environment values, auth paths, and raw diagnostics are never returned.

Every response carries an operation status of succeeded or failed, plus the optional safe projection. A revision conflict is not a response body status: it is an HTTP 409 error envelope with the CONFIGURATION_CONFLICT code. Example shape without secrets:

{
  "status": "succeeded",
  "configuration": {
    "configurationId": "cfg-example",
    "revision": 1,
    "status": "supported",
    "transportFamily": "hosted-api",
    "productId": "gemini",
    "endpoint": "https://generativelanguage.googleapis.com/v1beta",
    "selectedModelId": "gemini-2.5-pro",
    "notices": [],
    "availableActions": ["inspect", "select", "test", "update", "delete"]
  },
  "readiness": {
    "status": "ready",
    "ready": true,
    "evidenceStatus": "passed",
    "checkedAt": "2026-01-01T00:00:00.000Z",
    "acknowledgement": {
      "status": "accepted",
      "noticeId": "gemini-hosted-api",
      "noticeVersion": 1,
      "acceptedAt": "2026-01-01T00:00:00.000Z"
    },
    "action": "inspect",
    "explanation": "The exact configured review path is ready.",
    "remediation": {
      "code": "none",
      "message": "No remediation is required."
    }
  }
}

Readiness may also report skipped. A skipped live probe is evidence only and never enables a product. Remediation code enable-live-probe means the configuration must be tested again after prerequisites are satisfied.

create accepts an optional acknowledgement of the product's current notice and update requires one; a record without an accepted current notice reports acknowledgement-required ahead of any conformance verdict, and starting a review on it is refused with 503 SETUP_REQUIRED. The UIs send the acknowledgement automatically once the global provider consent is recorded in settings.providerConsent (see configuration).

The only other config routes are reads:

A passed models response carries source and cached describing where the list came from: live, cache, or snapshot mean the models.dev catalog (a fresh fetch, the hourly disk cache, or the bundled snapshot); provider-live or provider-cache mean the product's own model list supplied the ids — OpenRouter's and Ollama Cloud's public lists, or {endpoint}/models asked with the configuration's own credential for Z.AI, DeepSeek, Qwen International, Moonshot Open Platform, MiniMax International, and OpenCode Zen, and {endpoint}/openai/models for Google Gemini — with models.dev supplying names and prices for the ids it also knows; an id it does not know yet keeps tier: "unknown" and a description reading "Pricing unknown". cached is true exactly for cache and provider-cache. See Privacy for what each request carries.

For a product whose endpoints are billing pools — OpenCode Zen and OpenCode Go — the response is the union of both pools, so a provider-* source describes the bound pool's list only: rows that just the other pool serves come from the models.dev catalog and carry the bound pool's fetchedAt alongside it. Each row's endpointProfileIds names the endpoint profiles observed to serve it: a row served by one pool bills that pool, while a row both pools serve bills the pool tab active when the model is confirmed — that is the pool select carries.

There is no per-provider activate or delete route. GET …/models is the picker read path; test also discovers models as part of readiness probing. select both pins the exact model and makes that configuration the globally selected one. Its optional endpoint moves the configuration to the other billing pool of the same product — the pool the chosen model runs on — and is accepted only when it is the bound or sibling endpoint of that configuration's own pool, which today means OpenCode Zen and OpenCode Go. Every other endpoint is rejected with INVALID_ACTION, including the second endpoint of a product whose endpoints are separate accounts rather than pools, such as Moonshot Open Platform's other region. Omitting it leaves the endpoint alone. Either way select keeps the revision, so the credential binding survives; the conformance evidence is cleared as it already is on every model change.

Trust routes always require the shutdown token and fail closed when it is missing.

Git routes require repository trust.

Saved reviews persist an immutable execution snapshot, normalized usage when available, and one terminal outcome:

Findings are carried by completed, budget-exhausted, and cancelled outcomes only — a cancelled run keeps the partial findings its lenses produced before it was stopped, written by the cancel and shutdown drain. Every other failed outcome carries none. Receipts and usage summaries are client-safe and contain no secrets.

• Configuration
• Troubleshooting
• Privacy and security