AI agents: fetch the documentation index at llms.txt. Markdown versions are available by appending .md to any page URL, including this page's markdown.
API versioning
How Done Bear versions the REST surface, evolves the GraphQL schema, marks retiring fields with @deprecated, and sunsets documented fields.
Done Bear does not put a version in the URL. There is one API origin, https://api.donebear.com, and one GraphQL schema at /graphql. Breaking changes are announced, then marked, then removed.
REST versioning
The version travels in a header.
- Send
Api-Version: 1to pin a version. Omit it to get the current one. - Every response carries
Api-Version, including errors. - A version this server does not serve is refused with
400 unsupported_api_version, listing what it does serve, rather than being answered by a version you did not ask for.
curl -sS -D- -o/dev/null https://api.donebear.com/health -H "Api-Version: 1"The same declaration is machine-readable in the OpenAPI document: every operation takes the Api-Version header parameter, and the top-level x-versioning object names the current version, the supported versions, the deprecation headers, and the notice period.
REST deprecation
A retiring operation or version gains, at least 90 days before it stops answering:
Published with Blode.md