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

NumberWhereWhat it means
v1The path, https://app.grades.com/api/v1The API's major version: its shape, envelope and error format
The release, for example 3.182.0info.version of the OpenAPI descriptionThe 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 meta and 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 and code values of errors.
  • The wording of detail in 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 status and code, never on the text of detail.
  • 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.