Versioning
What can change under you, and what cannot.
The version is in the path: /api/v1/....
Additive changes ship into v1. A new field on a response, a new optional parameter, a new endpoint, a new scope. Write clients that ignore fields they do not know, because new ones will appear.
Anything that removes a field or changes its meaning waits for v2. The two
would run side by side while v1 is deprecated, with a Deprecation header and
a sunset date announced before either means anything.
One exception
Once, in October 2026, v1 lost fields without waiting for v2. The colours the
Profile Studio layout held left the answers of GET /api/v1/profile/layout
and GET /api/v1/profiles/{username}/layout: color on a background (the
page's, a section's or a block style's), textColor on a block's style,
and color, background and radius on a text element. They had arrived
with the layout's schema 2 on 12 October 2026 at 06:10 UTC and left the
same day, when text and backgrounds came to always follow the theme.
The rule was set aside this once because those fields had been in production
for less than a day. The schema stays 2. A PUT that still sends them
is not refused: they are dropped and the rest is stored. A background that
only had a colour becomes null, and tone auto, which used to read the
colour, reads only the image.
The rule still holds: any other removal waits for v2.
What is not a contract
messageon an error. Match oncode.- The order of keys in an object.
- The exact wording of anything meant for a person to read.
The website's own endpoints
There are two dozen route handlers under /api that are not this API. They are
the website's own, shaped around one screen each, and they change whenever that
screen changes. A bearer key is not accepted on any of them, so nothing can
come to depend on them by accident.