API v2
the older version
v2 keeps working as it is, with the same answers as before. New work should use v3.
The v2 reference
What is different in v3
| What | v2 | v3 |
|---|---|---|
| Ids | Integers, such as 7162384. | UUIDv7 strings that sort by time. |
| Lists | A bare array, with X-Pagination-* headers. | {"data": [...], "meta": {...}}, with page[size] and a page[after] cursor. |
| Token | Authorization: Bearer, or ?access-token= in the URL. | Only Authorization: Bearer, with scopes such as users:write. |
| Errors | A list of {field, message}. | Problem Details (RFC 9457) with a stable code. |
| Formats | JSON or XML. | JSON only, described by an OpenAPI 3.1 spec. |
| Todos | /public/v2/todos. | /public/v3/tasks, with priority and a description. |
| Writes | PUT and PATCH. | PATCH, with ETag and If-Match, and Idempotency-Key on POST. |
One token works on both versions; v2 calls need its v2 scope. Start with the v3 reference, or try v3 in the console.