From 48b8d86bf4bce61bc41f68dab14473b586ec85de Mon Sep 17 00:00:00 2001 From: Jeremiah Say Date: Sat, 19 Sep 2026 08:35:57 +0800 Subject: [PATCH] spec: correct a false claim in the README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit spec/README.md said the OpenAPI spec "was not linked from the developer docs". That is wrong. /developers/docs/ has documented it all along under "OpenAPI & clients" — GET /v1/openapi.json, a runnable curl, and guidance to point openapi-generator, Postman or Insomnia at it. The error came from checking the /developers/ hub and not the docs page it links to, then generalising from the one to the other. What the mirror is actually for is unchanged and narrower: the spec existed in no repository, so GitHub code search could not reach it and no API directory could index it from a file. That rationale stands on its own and did not need the overstatement. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01NRueWxopDXHoWY2dPvsmLG --- spec/README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/spec/README.md b/spec/README.md index 897ddbd..44e2769 100644 --- a/spec/README.md +++ b/spec/README.md @@ -8,11 +8,13 @@ The authority is the gateway, which serves it at . That URL is what `postman/generate.py` reads, and it is the one to integrate against. -But a live URL is not a discoverable one. It was not linked from the developer -docs, it is not in any repository, and nothing that crawls GitHub could find it. -A spec that tools cannot discover is, for most purposes, a spec that does not -exist — the same point `src/openapi.ts` makes upstream about a capability absent -from the machine-readable contract. +But a documented URL is not the same as a discoverable file. The API reference +at has documented this spec all +along, under "OpenAPI & clients", with a runnable `curl` and instructions to +point openapi-generator, Postman or Insomnia at it. What was missing is narrower +and purely mechanical: the spec existed in no repository, so nothing that crawls +or code-searches GitHub could reach it, and no API directory could index it from +a file. So this is a published mirror, for GitHub code search, API directories, codegen and coding assistants.