Versioning

The API

Every route lives under /api/v1. Breaking changes ship under a new version prefix while v1 keeps working. Each response carries an X-Cobuntu-API-Version header.

Within v1, changes are additive: new endpoints, new optional parameters, new fields in responses and new error codes. Read the fields you know and ignore the rest, and treat enums as open (a default branch for values you do not recognise).

One documented endpoint sits outside /api/v1: the marketplace categories read, GET /api/communities/{communityTag}/marketplace/categories. It is the unversioned surface, with a different prefix and auth posture; call it exactly as written.

The spec

openapi.yaml describes v1 (OpenAPI 3.1). Each operation carries x-required-scope, x-key-type, x-member-session and x-rate-limit, and its tag is one of the nine areas used across these docs.

The packages

@cobuntu/embed and @cobuntu/embed-react follow semantic versioning. While they are below 1.0, a minor version can change a signature; read the Changelog before upgrading.