Versioning

The version lives in the path: everything is under /v1/. A /v2/ would be a separate surface, served alongside /v1/ rather than replacing it.

What won't change within v1

• Fields won't be removed or retyped. A field that's a string today stays a string; a field that's there today stays there.
• Error codes are stable. error.code values are part of the contract — branch on them.
• Identifiers are stable. id on a save, board, or user survives renames and slug changes. Safe to store as a foreign key on your side.
• Paths and methods stay put. No endpoint moves or changes verb.

What can change without notice

• New fields may appear on any response object. Parse permissively — don't fail on unknown keys.
• New endpoints may appear under /v1/.
• The cursor encoding. Cursors are opaque. Pass next_cursor back verbatim; never parse, construct, or store one long-term.
• Error message strings. Human-readable, and reworded when a clearer wording comes along. error.code is the machine-readable half.
• Ordering within a page, beyond the documented sort (saves are newest first; boards follow your chosen sort preference on savee.com).
• Rate limits, if the current numbers turn out to be wrong. We'd raise them before lowering them, and the headers always tell you the current values.

Writing a client that lasts

• Read limits from the response headers rather than hardcoding 60 and 5,000.
• Treat cursors as strings you hand back, not data you understand.
• Ignore fields you don't recognise instead of erroring on them.
• Point code generators and agents at /v1/openapi.json rather than a copied snapshot, so they pick up additions on their own.

Staying current

The OpenAPI document is generated from the same schemas that serialize the responses, so it can't drift from what the API actually returns. It's the most reliable description of the current surface.