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

# Versioning

> The Moove API is versioned in the path. Today there is one public version: v1.

The Moove API is versioned in the URL path.

```
https://api.moove.xyz/v1/payment-link
```

Today there is one public version: **`v1`**.

## What can change inside a version

<Note>
  Treat the API as **additive** within a version. Your client must tolerate new fields appearing.
</Note>

Backwards-compatible changes ship inside `v1` without notice:

* New endpoints.
* New optional request fields.
* New response fields.
* New values in a non-exhaustive enumeration.
* Better error messages, under the same `code`.

Breaking changes do not. A change that removes a field, changes a type, makes an optional field required, or changes the meaning of an existing value would ship as a new path version.

## Writing a client that survives

<AccordionGroup>
  <Accordion title="Ignore unknown fields">
    Do not use a parser that errors on unrecognised keys. New response fields are additive and will appear.
  </Accordion>

  <Accordion title="Branch on `code`, never on `message`">
    Error codes are stable. Message text is written for humans and may be reworded at any time.
  </Accordion>

  <Accordion title="Handle unknown enum values">
    Payment link `status` is `active`, `completed` or `inactive` today. Give your client a default branch rather than crashing on a value it has not seen.
  </Accordion>

  <Accordion title="Do not hardcode page size">
    `limit` is returned in every list response. Read it rather than assuming it.
  </Accordion>

  <Accordion title="Pin the path version, not the schema">
    Call `/v1/…` explicitly. Do not build the path from a value fetched at runtime.
  </Accordion>
</AccordionGroup>

## The schema is the contract

The machine-readable schema is served live and covers the authenticated endpoints:

| Resource     | URL                                                                        |
| ------------ | -------------------------------------------------------------------------- |
| **Schema**   | [`https://api.moove.xyz/openapi.json`](https://api.moove.xyz/openapi.json) |
| **Rendered** | [`https://api.moove.xyz/docs`](https://api.moove.xyz/docs)                 |

Generate your client from it, and regenerate to pick up additions.

<Warning>
  The public `GET /v1/payment-link/{id}` is served in production but is not in the schema. A generated client will not include it — add it by hand from [Moove Payment Links](/api-reference/moove-receive/moove-payment-links#retrieve-a-payment-link).
</Warning>

## Deprecation

When a version is superseded, the current one keeps working while consumers migrate. Deprecations are announced before anything is withdrawn — nothing is removed without notice.

## Next

<CardGroup cols={3}>
  <Card title="Introduction" icon="code" href="/api-reference/introduction">
    Base URL and endpoints.
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/api-reference/errors">
    Stable error codes.
  </Card>

  <Card title="Moove Payment Links" icon="link" href="/api-reference/moove-receive/moove-payment-links">
    The v1 surface.
  </Card>
</CardGroup>