Endpoint map

In one sentence

The gateway serves about 80 routes; this page groups them by purpose, says which key each one needs, and shows the three calls most people make first.

The full schema of every route is in the generated HTTP API reference. The long prose guide, with every field and error, is the HTTP API guide. This page is the map between them.

API key

OpenAI-compatible

Chat, completions, responses, embeddings and models: what your app calls.

Dashboard key

Stats, evidence and cost

Stats, bills of materials, certificates, cost, replay and receipts.

Admin key

Admin and tasks

Versions, switches, task pins, erasure and the task registry, with an audit trail.

Public

Scout and pages

The research demo behind its budget guard, and the web pages.

The routes by purpose

flowchart LR
  app(["Your app"])
  watch(["Dashboard,<br/>monitors, auditors"])
  ops(["Operator"])
  web(["Browsers"])
  S["<b>Serve</b><br/>/v1/chat/completions<br/>/v1/completions, /v1/responses<br/>/v1/embeddings, /v1/models<br/>/v1/ratchet/feedback, no-train,<br/>examples"]
  P["<b>Prove</b><br/>/ratchet/bom<br/>/ratchet/versions/id/bom,<br/>certificate, proof<br/>/ratchet/receipts"]
  O["<b>Observe</b><br/>/ratchet/stats, kpis, cost<br/>/ratchet/drift, teacher, replay<br/>/metrics, /healthz, /readyz"]
  D["<b>Operate</b><br/>/ratchet/admin/*<br/>/ratchet/tasks<br/>/ratchet/cost/endpoint<br/>/ratchet/teacher/ack"]
  E["<b>Demo</b><br/>pages: / /dashboard /scout<br/>/scout/*<br/>/ratchet/demo/*, mock only"]
  app --> S
  app --> P
  watch --> O
  watch --> P
  ops --> D
  web --> E

  class S student
  class D gate
  class E outline

Reading this diagram. Read it from the left, from who calls to what they call. Your application only needs the first group, Serve: the OpenAI-shaped routes and the three Ratchet routes for feedback, no-train registrations and erasing its own examples. Prove holds the signed evidence: bills of materials, certificates, proofs and savings receipts. Observe is what the dashboard and your monitors read. Operate is for the person running the gateway: versions, switches, task pins and the task registry. Demo is the pages and the mock-only buttons, which answer 403 in live mode.

Who may call a route

Every route has one access level. A key goes in Authorization: Bearer <key> or in X-API-Key: <key>.

flowchart LR
  pub{{"public"}} --> r1(["Anyone"])
  api{{"api"}} --> r2(["A valid API key, once<br/>RATCHET_API_KEYS is set"])
  dash{{"dashboard, bom,<br/>metrics"}} --> r3(["Anyone on a public dashboard,<br/>else an admin or dashboard key"])
  adm{{"admin"}} --> r4(["An admin key,<br/>with an audit trail"])
  mock{{"mock"}} --> r5(["Mock mode only,<br/>403 in live mode"])

  class pub,api,dash,adm,mock gate
  class r1 ok
  class r5 outline

Reading this diagram. Each row is one access level, on the left, and who may call a route at that level, on the right. Public routes never ask for a key. API routes ask for a key only when RATCHET_API_KEYS is set. The read-only management routes (dashboard, bill of materials, metrics) are open on a public dashboard, which is the default in mock mode; in live mode they need an admin or dashboard key, and a gateway with neither configured refuses them. Admin routes always need an admin key in live mode. A route nobody has classified counts as dashboard level, so a new route starts private. On a public dashboard, a reader without a key still gets an answer, with client names replaced by pseudonyms. A missing or wrong key is a 401 or 403; on /v1/* a missing API key is a 401 invalid_api_key.

Note

The bill of materials routes also open to anyone with RATCHET_PUBLIC_BOM=1, so auditors can read provenance from a private gateway. The metrics route also accepts RATCHET_METRICS_TOKEN, so a scraper needs no dashboard key. Savings receipts are API-level: a key reads its own, an admin key reads all.

Every route

The Method and Path columns link to the generated reference for that operation.

OpenAI-compatible

Method	Path	Who	What it is for
GET	/v1/models	API key	The tasks as OpenAI model objects.
GET	/v1/models/{model_id}	API key	One model object.
POST	/v1/chat/completions	API key	The chat completion: student first, teacher when unsure.
POST	/openai/deployments/{deployment}/chat/completions	API key	The same chat route under an Azure-style path.
POST	/v1/embeddings	API key	Embeddings, passed through and never stored.
POST	/v1/completions	API key	Legacy text completions, run as chat.
POST	/v1/responses	API key	The stateless part of the Responses API, run as chat.
POST	/v1/moderations	API key	Not served: a typed 404.
GET	/v1/responses/{response_id}	API key	Not served: a typed 404 (stored responses).
POST	/v1/responses/{response_id}	API key	Not served: a typed 404.
DELETE	/v1/responses/{response_id}	API key	Not served: a typed 404.

End users and feedback

Method	Path	Who	What it is for
POST	/v1/ratchet/feedback	API key	A verdict on an answer, with an optional correction.
POST	/v1/ratchet/no-train	API key	Register an end user whose requests are never stored.
DELETE	/v1/ratchet/no-train	API key	Remove that registration.
DELETE	/v1/ratchet/examples	API key	Erase the caller’s stored examples (by end user, hashes or text).
GET	/v1/ratchet/requests/{request_id}	API key	The caller’s own request record.

Health and metrics

Method	Path	Who	What it is for
GET	/healthz	Public	Liveness plus mode and version.
GET	/livez	Public	Liveness (alias of /healthz).
GET	/readyz	Public	Readiness: ledger, teacher and student probes. 503 when the gateway cannot serve.
GET	/metrics	Dashboard key or metrics token	Prometheus metrics.

Stats and provenance

Method	Path	Who	What it is for
GET	/ratchet/stats	Dashboard key	The dashboard’s numbers: routes, tasks, clients, versions, events.
GET	/ratchet/requests/{request_id}	Dashboard key	One request’s record (metadata, never text).
GET	/ratchet/kpis	Dashboard key	The success metrics computed from the ledger.
GET	/ratchet/drift	Dashboard key	The label-free drift alarm’s state per version and task.
GET	/ratchet/bom	Dashboard key (public with RATCHET_PUBLIC_BOM=1)	The live adapter’s signed bill of materials.
POST	/ratchet/redact	Dashboard key	Preview what the redactor would store for a text.
GET	/ratchet/bom/public-key	Public	The public key that verifies bills of materials.
GET	/ratchet/teacher	Dashboard key	The teacher watch: check epoch, noise evidence, freeze state.
POST	/ratchet/teacher/ack	Admin key	Acknowledge a teacher drift freeze so training can resume.

Versions and evidence

Method	Path	Who	What it is for
GET	/ratchet/versions/{vid}/bom	Dashboard key (public with RATCHET_PUBLIC_BOM=1)	One version’s signed bill of materials.
GET	/ratchet/versions/{vid}/certificate	Dashboard key	One version’s certified precision.
POST	/ratchet/versions/{vid}/proof	Admin key	A proof that an example is, or is not, in a version’s training set.
GET	/ratchet/versions/{vid}/heldout	Admin key	A proof of absence from training for every golden row.

Cost

Method	Path	Who	What it is for
GET	/ratchet/cost	Dashboard key	Savings per token and by GPU-hours paid, break-even, recommendation.
POST	/ratchet/cost/endpoint	Admin key	Record that the student endpoint went up or down.

Ledger replay

Method	Path	Who	What it is for
GET	/ratchet/replay	Dashboard key	Replay a version’s traffic at another threshold or audit rate.
GET	/ratchet/replay/frontier	Dashboard key	The same replay over a range of thresholds.

Savings receipts

Method	Path	Who	What it is for
GET	/ratchet/receipts	API key	The caller’s sealed savings receipts.
GET	/ratchet/receipts/{period}	API key	One day’s receipt.
GET	/ratchet/receipts/{period}/proof/{request_id}	API key	An inclusion proof for one request in a receipt.
GET	/ratchet/receipts/{period}/leaves	API key	The leaves a receipt’s root commits to.

Tasks

Method	Path	Who	What it is for
GET	/ratchet/tasks	Dashboard key	Every registered task.
GET	/ratchet/tasks/{name}	Dashboard key	One task’s spec.
PUT	/ratchet/tasks/{name}	Admin key	Add or change an API task.
DELETE	/ratchet/tasks/{name}	Admin key	Remove an API task.
POST	/ratchet/tasks/validate	Admin key	Check task specs without saving them.

Admin

Method	Path	Who	What it is for
POST	/ratchet/admin/privacy/erase	Admin key	Erase stored examples for good (dry run by default).
GET	/ratchet/admin/export/{kind}	Admin key	A ledger table as NDJSON.
GET	/ratchet/admin/versions	Admin key	Versions, runtime switches and task pins.
GET	/ratchet/admin/flags	Admin key	The runtime switches.
POST	/ratchet/admin/versions/{vid}/rollback	Admin key	Roll a canary back.
POST	/ratchet/admin/versions/{vid}/retire	Admin key	Retire a version.
POST	/ratchet/admin/versions/{vid}/promote	Admin key	Move a version to a canary stage or to live.
POST	/ratchet/admin/student/disable	Admin key	Switch the student off.
POST	/ratchet/admin/student/enable	Admin key	Switch the student on.
POST	/ratchet/admin/releases/freeze	Admin key	Freeze releases (rollbacks and alerts keep running).
POST	/ratchet/admin/releases/unfreeze	Admin key	Unfreeze releases.
POST	/ratchet/admin/training/pause	Admin key	Pause Night School training.
POST	/ratchet/admin/training/resume	Admin key	Resume training.
PUT	/ratchet/admin/settings	Admin key	Set a runtime setting such as the audit rate.
POST	/ratchet/admin/tasks/{name}/pin	Admin key	Pin a task to the teacher.
DELETE	/ratchet/admin/tasks/{name}/pin	Admin key	Remove a runtime pin.
POST	/ratchet/admin/tick	Admin key	Run the release gate’s tick now.
GET	/ratchet/admin/audit-log	Admin key	The newest admin actions.

Demo controls (mock only)

Method	Path	Who	What it is for
POST	/ratchet/demo/day	Mock mode only	Run a simulated day of traffic.
POST	/ratchet/demo/break-next	Mock mode only	Corrupt the next trained adapter, to show a rollback.
POST	/ratchet/demo/student-outage	Mock mode only	Take the student down, to show the breaker.
GET	/ratchet/demo/sample-example	Mock mode only	A stored example, for the proof demo.
POST	/ratchet/demo/teacher-drift	Mock mode only	Make the mock teacher drift, to show the watch.
POST	/ratchet/demo/reset	Mock mode only	Reset the mock demo.

Scout

Method	Path	Who	What it is for
GET	/scout/examples	Public	Example questions for Scout.
GET	/scout/recorded	Public	Recorded Scout runs.
GET	/scout/recorded/{rid}	Public	One recorded run.
GET	/scout/status	Public	The budget guard’s status.
POST	/scout/judge	Public	Unlock judge access with a code.
DELETE	/scout/judge	Public	End judge access.
GET	/scout/stream	Public	Run Scout and stream its events.
POST	/scout/run	Public	Run Scout and return the result.

Pages

Method	Path	Who	What it is for
GET	/	Public	The story page.
GET	/dashboard	Public	The dashboard page.
GET	/scout	Public	The Scout page.
GET	/lite	Public	The story page without a build step.
GET	/lite/dashboard	Public	The dashboard page without a build step.
GET	/lite/scout	Public	The Scout page without a build step.

Routes the schema leaves out: /docs, /redoc and /openapi.json (off in live mode), and the static files under /assets/.

Three examples

The examples run against a gateway in mock mode, with no keys and no network:

RATCHET_MODE=mock uvicorn ratchet.gateway:app --port 8000

In live mode, add Authorization: Bearer $KEY with one of your API keys.

1. A chat completion with a task

X-Ratchet-Task says which task the request belongs to. Without it the request uses the default task (see task selection for the other ways to name one).

curl -s localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Ratchet-Task: ticket-triage" \
  -d '{"model": "ratchet",
       "messages": [{"role": "user", "content": "Where is my refund for order 1234?"}]}'

The same call with the OpenAI Python SDK:

import openai

client = openai.OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed-in-mock-mode")
msgs = [{"role": "user", "content": "Where is my refund for order 1234?"}]

resp = client.chat.completions.create(
    model="ratchet",
    messages=msgs,
    extra_headers={"X-Ratchet-Task": "ticket-triage"},
)
print(resp.choices[0].message.content)

2. Read ratchet.request_id and send feedback

Every chat response carries a ratchet block next to the usual fields. request_id names the request; served_by says whether the student or the teacher answered. A verdict on a request goes back with that id. An incorrect verdict may also carry the right answer, which then becomes a human-labelled training example (when the task and your opt-outs allow it).

import httpx

meta = resp.model_extra["ratchet"]
print(meta["request_id"], meta["served_by"], meta["escalated"])

r = httpx.post(
    "http://localhost:8000/v1/ratchet/feedback",
    json={"request_id": meta["request_id"], "verdict": "correct"},  # add headers={"Authorization": ...} in live mode
)
print(r.status_code, r.json())

With curl, using the id from the response:

curl -s localhost:8000/v1/ratchet/feedback \
  -H "Content-Type: application/json" \
  -d '{"request_id": "req_...", "verdict": "correct"}'

The answer is {"object": "ratchet.feedback", "request_id": "req_...", "verdict": "correct", "updated": false, "correction": null}. updated is true when an earlier verdict on the same request was replaced. A key can give verdicts on its own requests only; any other id is a 404.

3. The error envelope

Errors on /v1/* use OpenAI’s envelope, so the SDK raises its typed exceptions. Every response, errors included, carries an x-request-id header.

import openai

try:
    client.with_options(max_retries=0).chat.completions.create(model="ratchet", messages=msgs, temperature=3)
except openai.BadRequestError as e:
    print(e.status_code, e.code, e.param, e.response.headers["x-request-id"])
    # 400 invalid_value temperature req_...

The body of that response:

{
  "error": {"message": "Invalid value for 'temperature': expected a number from 0 to 2, but got 3 instead.",
            "type": "invalid_request_error", "param": "temperature", "code": "invalid_value"},
  "detail": "Invalid value for 'temperature': expected a number from 0 to 2, but got 3 instead.",
  "request_id": "req_0b6f3a7c2d1e4f5a8b9c0d1e2f3a4b5c"
}

error has OpenAI’s four fields. detail repeats the message for older clients. Routes outside /v1 answer {"detail": ...} and put the id in x-request-id.

sequenceDiagram
  participant C as Your app
  participant G as Gateway
  participant Student as Student
  participant Teacher as Teacher
  participant Ledger as Ledger
  C->>G: POST /v1/chat/<br/>completions
  alt the request breaks a rule
    G-->>C: 400 envelope,<br/>x-request-id
  else the student is sure
    G->>Student: three samples
    Student-->>G: answers
    G-->>C: 200, request_id,<br/>served_by student
  else the student is unsure
    G->>Teacher: escalate
    Teacher-->>G: answer
    G->>Ledger: store it, if valid
    G-->>C: 200, request_id,<br/>served_by teacher
  end
  C->>G: POST feedback:<br/>request_id, verdict
  G->>Ledger: record the verdict
  G-->>C: 200 ratchet.feedback
  Note over G,Ledger: a correction becomes<br/>a human-labelled example

Reading this diagram. A request is checked first, and a broken rule is a 400 in OpenAI’s envelope before anything is spent. Otherwise the student answers when it is sure, and the teacher answers and has its answer stored when it is not. Either way the response names the request in ratchet.request_id. Feedback comes later, as a separate call to /v1/ratchet/feedback that quotes that id. The verdict is recorded in the ledger. It never promotes or rolls back a version; it is reported as human precision.

Where the reference pages come from

The generated pages are not typed by hand, so they cannot drift from the code.

flowchart TB
  code["gateway.py<br/>app.openapi()"] --> script
  cfg["config.py<br/>KNOWN_ENV"] --> script
  cli["each tool's<br/>--help"] --> script
  mk["Makefile<br/>targets"] --> script
  script["export-reference.py"] --> o[("openapi/<br/>ratchet.json")]
  script --> e[("generated/<br/>env.json")]
  script --> c[("generated/<br/>cli.json")]
  o --> h["HTTP API<br/>pages"]
  e --> ep["Environment<br/>variables page"]
  c --> cp["Command<br/>line page"]
  h --> site(["Docs site"])
  ep --> site
  cp --> site
  hand["Endpoint map<br/>and guides,<br/>by hand"] --> site

  class script gate
  class o,e,c store
  class hand outline

Reading this diagram. The script at the top imports the gateway in mock mode, reads the settings registry, runs every command line tool with --help and reads the Makefile. It writes three committed data files. The site turns those files into the HTTP reference, the environment variable page and the command line page. This page and the guides are written by hand and link to the generated pages. After you change a route, a setting or a command, run python docs-site/scripts/export-reference.py and commit the result.

Next steps

• HTTP API guide: every field, header and error code.
• Generated HTTP reference: the schema of every operation.
• Environment variables and Command line.
• Python API: call the cascade without HTTP.