Skip to main content
The API version is part of the path. Everything documented in this tab lives under /v1, and /v1 is the only public API: other routes that the muveya console uses are not a public contract, may change at any time and must not be called by integrations.

​
The promise

  • Inside /v1, changes are additive. An operation, a field or a value your integration relies on is not removed or renamed inside /v1.
  • A breaking change needs a new version. It ships as a new major version in the path (/v2), with a migration window. /v1 is not broken in place.
  • The contract is checked on every change. The public OpenAPI contract behind the Endpoints pages is generated from the muveya server code, and every change to it is compared with the previous version by an automatic compatibility check that rejects the breaking changes listed below.
The version shown inside the OpenAPI document is the revision of that document. The API version you integrate with is the /v1 in the path.

​
What counts as breaking

muveya treats these changes to /v1 as breaking, and does not make them inside /v1:

​
What can change inside /v1

These changes are additive and can arrive at any time, announced in the changelog:
  • New operations and new resources.
  • New optional query parameters and headers.
  • New optional fields in responses.
  • New values in response enums, for example a new order status, a new stock movement type or a new analytics metric key.
  • New error code values.
  • New scopes.
  • Different wording in human text: error title and detail, briefing labels, descriptions in this reference.
  • Operational values that the API reports at runtime, such as the rate-limit budget in the response headers.
A field that appears because a key gained a scope (for example cost fields with catalog.cost:read) is not a change to the contract: it was always documented as optional.

​
Write a tolerant client

1

Ignore fields you do not know

Parse only the fields you use. Do not fail when a response contains a field that is not in your model.
2

Treat enums as open

Give every switch on a status, a movement type or a metric key a default branch. A new value must not crash your integration; log it and handle it as “other”.
3

Treat optional fields as optional

A field marked optional can be absent. It is never sent as null instead (except three analytics fields, value, averageHours and maxAgeHours, described in the reference). Check for presence before you read it.
4

Branch on the code, fall back on the status

Handle the error codes you know and use the HTTP status for any code you do not know yet. See Errors.
5

Never branch on human text

title, detail and label change with the language and the wording. Use keys, codes and ids.
6

Do not depend on the cursor format or on key order

Cursors are opaque and JSON key order is not meaningful.

​
Deprecation

No /v1 operation or field is deprecated today, and no response carries deprecation headers. When a /v2 exists, /v1 will be given an announced retirement window. The retirement will be published in the changelog before it takes effect, and muveya plans to signal it on responses with the standard Deprecation and Sunset headers.

​
What is not in /v1 today

Features that are not documented in this tab are not available, for example creating or changing orders through the API, or webhooks. If they arrive, they arrive as additive changes and are announced in the changelog. The only API key format issued today is mvy_test_ (see Authentication).

​
Where changes are announced

  • The changelog lists customer-visible changes, newest first.
  • The Endpoints pages are rebuilt from the contract whenever it changes, in English, Spanish and Portuguese.