Skip to main content
The version is in the path: https://api.pinakelai.com/v1. There is no version header.

​
What can change within v1

v1 only grows. These changes can happen at any time, announced in the changelog:
  • new endpoints;
  • new optional query parameters and include values;
  • new fields in responses, including inside nested objects;
  • new values in open enumerations, such as status.value, mark.feature, mark.kind, the feed’s type, and error codes;
  • new problem types and new response headers;
  • reworded title and detail texts in errors.
Anything else, such as removing or renaming a field, changing a field’s type or meaning, or making an optional parameter required, is a breaking change and ships as /v2.

​
Deprecation

Before a version or an endpoint is retired, its responses carry: The Sunset date is at least six months after the deprecation is announced. Log these headers when you see them; they are exposed to browsers too.

​
Outside the stability guarantee

  • source_record (include=source_record): the stored source document, whose structure can change without notice.
  • RateLimit and RateLimit-Policy header syntax, until the IETF draft is final.
  • name_key values, which change when name normalization improves. The field itself is stable.
  • The format of cursors and of the uid part of ids. Both are opaque: store and send them, never parse them. The tm_ prefix and register code of an id are stable.
  • The order of keys in JSON objects and of records with equal sort values beyond the documented tie-break.

​
Writing a client that keeps working

  • Ignore fields you do not know.
  • Treat an unknown enumeration value as other, and an unknown feed type as something to skip.
  • Branch on error type, never on title or detail.
  • If you generate types from /v1/openapi.json, allow additional properties. Response enumerations there are marked x-extensible-enum: generate them as open strings, not closed enums.
  • Follow the changelog. It names every change that could matter to you.

​
Earlier paths

Pinakel’s earlier record API at /data/v1 has been retired.