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

# Versioning

> Versioning: Set Aside Money developer API reference.

The API is versioned in the path. Today there is one version:

```
https://api.setaside.money/v1
```

## What we can change without warning

These are additive, and your integration should tolerate them:

* **New fields on existing responses.** Parse the fields you need and ignore the rest. Do not assert
  on an exact object shape.
* **New endpoints.**
* **New optional request parameters.**
* **New error codes**, within the existing `type` values. Branch on `type` first, then handle the
  specific codes you care about, and treat anything unrecognised as a generic failure of that type.
* **Wording of `message`.** It is written for a human reading a log. Never parse it.

## What counts as breaking

These will not happen inside `v1`:

* Removing or renaming a field, endpoint, or error `type`.
* Changing a field's type, including the units of a monetary amount.
* Making an optional request parameter required.
* Tightening validation so a request that used to succeed now fails.

If we need one of those, it goes in `/v2`, and `/v1` keeps working.

## Deprecation

If an endpoint is going away, in this order:

1. It gets marked deprecated in this documentation and in the OpenAPI description.
2. Responses start carrying a `Deprecation` header and a `Sunset` header with the removal date.
3. We email the account owner for any key that has called it in the previous 30 days.
4. At the earliest, it is removed **six months** after step 2.

## Pinning a client

The OpenAPI description at
[api.setaside.money/v1/openapi.json](https://api.setaside.money/v1/openapi.json) is generated from
the routes themselves, so it cannot drift from what is actually running. If you generate a client
from it, regenerate periodically to pick up new endpoints. Nothing you already use will move.

Money is always an integer number of cents, and it will stay that way inside `v1`. That is the
field type most likely to trip up a client and the one least likely to change.


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