Home · Docs · Schemas · PostItem
PostItem — one post, with the four metrics that exist everywhere
The normalised post shape. `metrics` carries likes, replies, reposts and quotes — and nothing else, because nothing else exists on every platform we read.
PostItem has 9 fields: 7 nullable, 0 guaranteed by the contract's required list. Every number on this page is counted from the field map at render time — none of them is written down.
Fields
| Field | Type | Nullable | Required |
|---|---|---|---|
id | string | no | no |
url | string | yes | no |
text | string | yes | no |
text_html | string | yes | no |
title | object | yes | no |
position | object | yes | no |
published_at | string | yes | no |
thumbnail_url | string | yes | no |
metrics | object | no | no |
9 rows above, 4 of them with a transcription from the contract and 1 with a note of ours.
What the fields mean
Only the fields with something measured or decided about them appear here. A field whose name and type say everything gets no paragraph, rather than a generic one.
text_html
From the contract: Mastodon only. Third-party HTML, unsanitised — sanitise before rendering or you have an XSS hole. `text` is the same content already stripped.
title
From the contract: Always null: a status has no title.
position
From the contract: Always null: chronological order is not a ranking.
thumbnail_url
From the contract: Null on bluesky and mastodon — the image embed has not been measured on a large enough sample to promise a shape.
metrics
Our note: Four keys: likes, replies, reposts, quotes. No views, no saves, no shares — those exist on some platforms and not others, and a field that is present for three networks and absent for eight breaks the promise that the response shape is the same across all of them.
How this page stays true
The field list, the two flags and the closed value sets are generated from the contract this API serves, and a test compares them against the live /openapi.json in both directions: a field in the contract with no documentation fails, a documented field the contract does not have fails, and a wrong nullable or required fails. The prose marked our note is not covered by that test — it is authored, and labelled so you can tell.
The machine-readable source is at /openapi.json. If you are generating a client, use that rather than this page.
The other 7 schemas
ApiError · SeriesPoint · Item · Mover · Author · PostsEnvelope · ProfileEnvelope