API changes#

Records behavioural changes that affect integrations.

Current state#

Area	State
Version	v1
Authentication	JWT with refresh token rotation
Server-to-server key	🔴 not usable — see Authentication
Permissions	enforced
Warehouse module	read-only from outside
Specification	covers only the auth endpoints

Things we know about and that may change:

Limitation	Note
Parameters in the URL	writes included; the body is not read
Two response shapes	reads without an envelope, writes with one
Errors with status 200	only 401, 403 and 429 are distinguished
Inconsistent error envelope	sometimes three keys, sometimes five
The HTTP method is ignored	`GET` on a delete action deletes
Owner collections	`get-all` and `get-by` are denied to owners
Missing HTTP wrappers	the cart, checkout, "my" listings
Silent discarding of write data	the only trace is in the server log

Treat this list as the contract

The behaviour described here is what you can build on. If it changes, it appears here.

The permission switch applies to the whole API

Changing the mode changes behaviour across every resource at once. Your client must handle a denial on an action that used to work.

Write your client defensively

Check the content type, the presence of keys and the status code. Responses may differ in detail from resource to resource.

Item	State
Scopes for the server-to-server key	in progress
Extending the specification to CRUD resources	planned
HTTP wrappers for missing operations	as integrations need them

Need something that is not available?

Contact the operator. Many operations exist and merely lack an HTTP wrapper — adding one is a matter of one resource, not a new feature.