Developers
Versioning
The API version is in the path: /api/v1. Inside v1, changes arrive as additions: new operations, new optional parameters and new response fields.
Two version numbers
| Number | Where | What it means |
|---|---|---|
v1 | The path, https://app.grades.com/api/v1 | The API's major version: its shape, envelope and error format |
The release, for example 3.182.0 | info.version of the OpenAPI description | The app release that serves the API. It changes with every release, including releases that change nothing in the public API |
The API changelog lists, release by release, which public operations were added or removed and which got new parameters or fields. It is generated from the OpenAPI description of each release.
How changes arrive in v1
These changes happen inside v1 at any release, without notice, and a well-written client keeps working through them:
- New operations and new tags.
- New optional query parameters and optional body fields.
- New fields in responses, in
metaand in webhook payloads. - New webhook events (you receive only the events you subscribed to, unless you subscribed to all).
- New values in fields that list kinds of things, such as review sites (
site), sources andcodevalues of errors. - The wording of
detailin errors and of descriptions.
Since October 8, 2026 no public operation or parameter has been removed or renamed; the changelog shows every release.
Write a client that keeps working
- Ignore fields you do not know instead of failing on them; do not validate responses against a closed schema.
- Treat enum-like strings (sites, statuses, error codes) as open: handle the values you know and have a default for the rest.
- Branch on
statusandcode, never on the text ofdetail. - Treat cursors and ids as opaque strings.
- Send only the body fields an operation documents: unknown fields answer
400. - Watch the changelog or its RSS feed for what is new.
Deprecated fields
A deprecated field or parameter says so in its description in the API reference, with what to use instead. The API does not send Deprecation or Sunset headers. A formal deprecation policy with a notice period is not published yet.