Working with the API

Versioning and deprecation

What may be added under /v1 without notice, what is never changed in place, and how a shape that is going away says so on every answer.

The platform's version is in its path, /v1, and the rule under it is that no working integration breaks on the day a change ships. A change that would break one is added beside the old shape instead of replacing it: the old shape keeps its answer, and says on the wire — not only on a page — that it is going away. When a change has not been able to keep to that, the changelog says so on the day it shipped, and what to do instead.

#What is added without notice

A field in an answer, and an optional parameter or body field in a request.
A value in an answer's list of values: a model's address where model is printed, a word in a status or a reason, an error code.
A path, or an operation on one.

So read what you know and pass over what you do not: ignore a field you do not use, treat a value you have not seen as "something else", and act on an error code you do not know by the advice every refusal carries beside it — error_type, retry and charged (Errors).

#How a shape that is going away says so

The answer to a request that uses it carries two headers (RFC 9745):

Deprecation: @<seconds> — the day the shape stopped being the published contract, as a Unix time.
Link: <https://auray.ai/docs/…>; rel="deprecation" — the page that names what to send instead.

So a client library or a proxy log can find every caller still using it without anybody reading prose. No Sunset header is sent: retiring a shape is a separate decision, dated when it is taken and announced in the changelog before it applies, and the header would be a promise nobody has made.

#Deprecated today

Shape	Since	Send instead
`POST /v1/uploads` naming `product` and no `address`	2026-09-26	`address`, the model the file is for: the bucket, the scope, the kinds and the size follow from it (Uploads).
`POST /v1/uploads` or `GET /v1/uploads/{path}` naming `product: "video"`	2026-09-26	Nothing: no published video address takes a file, and the bucket stays readable for the keys that used it (Uploads).
A body field an address does not declare, or a value it would refuse	2026-09-26	Only the fields `GET /v1/models/<address>/openapi.json` lists, within the ranges it prints. Refused once enforcement starts, no sooner than 30 days after the warnings began (`unknown_field`).
A catalogue model's body that breaks one of the rules its fields keep together	2026-10-01	A body that keeps every rule the address's openapi.json lists under `x-auray-rules`; refused once enforcement starts (`bad_value`).

The older names a key's scopes had are not on this list: they are still accepted, and Authentication says which name each one now has.