API response schemas

8 schemas and 71 fields in total — 31 nullable, 17 guaranteed by a contract required list. Those four numbers are counted from the field map when this page renders, not written into it.

The nullable count is high on purpose. A field we could not read comes back null, never 0 and never false, because a zero would be a claim about the account and a false would be a claim about the platform. The Author page is the clearest case: all of its fields are nullable, and each null means something specific.

The 8 schemas

• ApiErrorEvery 4xx and 5xx from the API carries this object. The `error` value is a stable string you can branch on; the extra fields appear only for the errors that have something to report.
• SeriesPointA single reading in an item's series: where it sat, how many points it had, how many comments. The archive keeps one of these per item per hour and never deletes them.
• ItemWhat `archive/trends` returns: an item, when it entered the ranking, when it left, its best position, and the full series of hourly readings behind it.
• MoverWhat `archive/movers` returns. The ranking key is `points_gained`, not `points` and not `position` — the question is what accelerated, not what is big.
• AuthorThe normalised profile shape, identical across all platforms. All twelve fields are nullable, and that is the design: a field we cannot read comes back null, never 0, because a zero would be a claim about the account.
• PostItemThe normalised post shape. `metrics` carries likes, replies, reposts and quotes — and nothing else, because nothing else exists on every platform we read.
• PostsEnvelopeEvery posts endpoint answers with this envelope. Eight fields, all required: you can read `success` and `credits_used` without checking whether they came.
• ProfileEnvelopeThe profile envelope carries the credit accounting that the posts envelope does not: what this call cost, what is left of the monthly allowance, and what you bought.

Why these pages can be trusted

The field lists are generated from the contract this API serves, and a test compares them against the live /openapi.json in both directions. A field the contract has and these pages do not fails the build's test run; so does a field these pages claim and the contract does not have; so does a wrong nullable, a wrong required, or a closed value set that drifted. Documentation that invents contract is the failure mode this family exists to avoid, so it is the one thing here that is checked mechanically rather than carefully.

What the test does not cover is the prose: the paragraphs labelled our note on each page are authored, and a rewritten description upstream would not turn them red. They are labelled so you can tell which sentences carry that risk.