16. The operator surface
/internal/v1/* requires an internal_ key and refuses pk_live_ outright.
Customer keys are refused here and internal keys are refused on /v1/*; there
is no overlap.
| Endpoint | Purpose |
|---|---|
GET /internal/v1/providers | every provider row, enabled or not |
PATCH /internal/v1/providers/{name} | enable/disable, timeout, capability overrides |
| `GET | PUT /internal/v1/catalog/models/{name}/pricing` |
POST /internal/v1/catalog/models | seed catalog rows |
| `GET | POST /internal/v1/admin/model-bindings` |
POST /internal/v1/admin/byok/reseal | carry every sealed BYOK credential onto the current master-key version (rotation step two; needs internal:credentials:reseal) |
POST /internal/v1/blueprints | author a self-hosting recipe |
GET /internal/v1/rtr/providers | what the router actually registered at boot |
POST /internal/v1/db/query | read-mostly SQL |
GET /internal/v1/forensics/* | orphan pods, instance composites |
POST /internal/v1/scenarios/{name}/run | end-to-end gates |
Operator scopes are separated on purpose: internal:catalog:manage files a
model (inert), internal:pricing:manage changes a rate (moves money),
internal:providers:manage decides whether an upstream serves at all. A key
trusted with one is not thereby trusted with the others.
Provider changes apply without a restart. The router fingerprints the
provider rows every 30 seconds and hot-swaps its registry when they change;
every patch response says applies_within_secs: 30.
Two more doors for operators onboarding a tenant:
| Endpoint | Purpose |
|---|---|
GET /internal/v1/tenant-keys · PATCH /internal/v1/tenant-keys/{id} | read a tenant's keys; set a key's scope set (absolute, audited) — the only way to grant keys:write |
POST /internal/v1/db/query | the current path for custom_overrides on an entitlement, e.g. {"monthly_credits": null, "max_concurrent_instances": null} for metered-but-unbounded |
The operator surface answers on https://api.opennozzle.com/internal/v1 and on
http://api.49-12-240-8.traefik.me. Prefer the TLS host: an internal_ key on
the plain-HTTP one crosses the network in the clear. The HTTP host is kept as
the fallback for the case where a certificate problem would otherwise lock an
operator out of the control plane used to fix it.