> ## Documentation Index
> Fetch the complete documentation index at: https://muveya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning and stability

> What stays stable inside /v1, which changes muveya treats as breaking, how to write a client that tolerates additive changes, and where changes are announced.

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`:

| Change | Example |
| - | - |
| Removing an operation or changing its `operationId` | Removing `GET /v1/orders` |
| Removing a documented response status of an operation | No longer answering `404` where it was documented |
| Removing a query, path or header parameter | Dropping `status` from `GET /v1/fulfillments` |
| Adding a new **required** parameter | Making `limit` mandatory |
| Removing an accepted value from a request enum | No longer accepting `weekly` as `period` |
| Making a request body property required | Requiring `period` in `POST /v1/analytics/exports` |
| Removing a response property | Dropping `hasMore` from lists |
| Turning a guaranteed response property into an optional one | Making `status` optional on `Order` |
| Removing a value from a response enum | No longer returning `in_transit` as a box status |
| Changing the type of a field | Turning `onHand` from integer into string |

## What can change inside `/v1`

These changes are additive and can arrive at any time, announced in the [changelog](/docs/en/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 `label`s, 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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".
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/docs/en/api-reference/errors).
  </Step>

  <Step title="Never branch on human text">
    `title`, `detail` and `label` change with the language and the wording. Use keys, codes and ids.
  </Step>

  <Step title="Do not depend on the cursor format or on key order">
    Cursors are opaque and JSON key order is not meaningful.
  </Step>
</Steps>

## 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](/docs/en/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](/docs/en/api-reference/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](/docs/en/api-reference/authentication)).

## Where changes are announced

* The [changelog](/docs/en/changelog) lists customer-visible changes, newest first.
* The **Endpoints** pages are rebuilt from the contract whenever it changes, in English, Spanish and Portuguese.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.