The schema is generated from the code that validates
Hand-written API documentation is a promise about code. Generated documentation is a description of it.
One source, three faces
Every request body on this service is described once, as a validator in the code. From that single definition come three things: the check the server actually performs, the component schemas in the OpenAPI document at /openapi.json, and the input schemas the MCP tools advertise to a model.
That is why a generated client and the server cannot disagree about whether a field is optional. If the rule changes, all three change in the same commit, because they are the same object. The only hand-written part is the list of paths, and a test fails the build if a documented path has no route behind it.
- Point your generator at /openapi.json and get types for pages, blocks, patches and errors.
- Or read it once and write the four calls you need by hand — the surface is small enough that a client library is optional.
- Use the same document to build a custom GPT action or a tool definition for your own agent framework.
- Check the changelog page before upgrading: field names are stable, and anything removed is announced there first.
What the document does not tell you
- Which of ten templates suits a photographer. That is taste, and it lives in the prose documentation.
- That a short path must be unique within a page — a constraint no schema can express, returned as an error instead.
- That creating a page needs no authentication at all. Security schemes describe what may be sent, not what is required.
- What to do when something fails. That is the hint on the error, which is generated from the server too.
Prose for models, schema for machines
A schema is exact and says nothing about intent. A model reading only the schema will produce a valid page that is somehow wrong: eleven links, a generated bio, a template that fights the content. So the same API is documented twice — as a schema for code and as Markdown for whoever has to decide what belongs on the page.
Both are generated, both are served at fixed addresses, and a test holds that every endpoint, every error code and every tool name appears in the prose as well. Documentation that cannot drift is the only kind worth writing for an audience that reads it literally.