ModelviaManaged AIDocumentation

DOCUMENTATION

API versioning

What the /v1 prefix promises, what we treat as a breaking change, and how much warning you get before one lands.

/v1 is the only supported surface

Every supported endpoint sits under /v1: the model listing, both chat surfaces, the receipt lookup, and the client, member and operator APIs. If a path does not begin with /v1, it is not part of the supported interface and may change or disappear without notice.

Two paths sit outside it on purpose. /health is a process probe and /ready is the readiness probe; they exist for operators and for the status page, and they are not an API to build against.

There is no v2 and no date for one. If the interface ever needs an incompatible shape, it gets a new prefix and /v1 keeps working through the deprecation period below rather than changing underneath you.

What counts as a breaking change

A change is breaking if a correct integration that worked yesterday stops working, or starts being wrong, without anyone editing it.

Breaking — these get notice

  • Removing an endpoint, a field in a response, or an accepted request field.
  • Renaming any of those, including a change of letter case.
  • Changing the type of a field, or the units it is expressed in.
  • Making an optional request field required, or narrowing what a field accepts.
  • Changing the meaning of an existing error code, or the HTTP status a named refusal returns.
  • Removing an event from the streaming sequence, or changing the order events arrive in.

Not breaking — these can ship any day

  • Adding a new endpoint.
  • Adding a field to a response. Ignore fields you do not recognise.
  • Adding an optional request field with a default that preserves today's behaviour.
  • Adding a new value to an open set, such as a new model id in the listing or a new refusal code.
  • Adding or removing a model route, or changing which upstream serves one. The catalogue is data, not interface.
  • Changing prices, which are governed by rate-card acceptance rather than by this policy.
  • Performance, wording of human-readable messages, and anything behind the API.

Two consequences worth stating outright. A new model appearing or disappearing from GET /v1/models is not a breaking change — read the listing rather than hard-coding a model id. And a new refusal code is not a breaking change — handle an unrecognised code by its HTTP status.

Deprecation notice period

Draft policy — proposed, not yet adopted

The 90 days below is what we intend to commit to. It has not been adopted as a contractual term yet. Until it is, treat it as our stated intention and ask us in writing if you need it to be binding.

When something on /v1 is deprecated, we propose to give at least 90 days' notice before it stops working. During that window:

  • the deprecated behaviour keeps working exactly as it did, with no silent degradation;
  • the deprecation is published on the changelog with the removal date;
  • account contacts are emailed at the start of the window and again two weeks before removal;
  • the replacement is documented before the notice period starts, not during it.

Two exceptions, and we will say which one applies: a security fix that cannot wait, and a change a provider or the law forces on us. In those cases we give as much notice as we have.

Writing a client that survives all this

  • Ignore response fields you do not recognise rather than failing on them.
  • Read context_length, max_output_tokens and price from GET /v1/models instead of hard-coding them.
  • Send an Idempotency-Key so a retry settles the original request rather than starting a second one.
  • Branch on the HTTP status first and the refusal code second, so an unfamiliar code still lands in the right branch.
  • Keep the base URL in configuration. It is https://api.modelvia.dev, and only the OpenAI-shaped recipes append /v1 themselves — see your first call.