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

# Versioning

> Date-based API versions and the version switcher.

The Simply Tokenized API uses **date-based versioning** (similar to Stripe). Each version represents a contract for request and response shapes.

## Current version

| Version      | Status   | Environments                                                     |
| ------------ | -------- | ---------------------------------------------------------------- |
| `2026-07-02` | **Beta** | **Development only** (`https://dev.go.simplytokenized.com/_api`) |

<Note>
  `2026-07-02` is the only supported version today. It is marked **beta** because the API is still evolving. Breaking changes may occur before a stable release. Use the **development** base URL when testing this version.
</Note>

Use the **version switcher** in the top navigation of these docs to browse documentation for a specific contract date. The switcher shows a **Beta** badge for `2026-07-02`.

## Environment base URLs

| Environment | Base URL                                  |
| ----------- | ----------------------------------------- |
| Development | `https://dev.go.simplytokenized.com/_api` |
| Staging     | `https://stage.go.floris3.com/_api`       |
| Live        | `https://go.floris3.com/_api`             |

Beta API versions are only available on **development**. Staging and live will receive stable versions when they are released.

## How version is chosen

When you call `POST /_api/auth`, the API version is resolved in this order:

1. `api_version` in the auth request body (if provided)
2. Default version on the API credential
3. Recommended version (`2026-07-02`)

The resolved version is:

* Embedded in the JWT as the `api_version` claim
* Returned in the `ST-Api-Version` response header on every API response
* Marked as beta via `ST-Api-Version-Beta: true` for `2026-07-02` (development)

## Beta indicator header

Responses for beta version `2026-07-02` on **development** include:

```
ST-Api-Version: 2026-07-02
ST-Api-Version-Beta: true
```

Integrators can use this header to detect beta contract versions programmatically.

## Version format

Versions must match `YYYY-MM-DD` and be listed in the supported versions set. Requesting an unsupported version returns:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "message": "Unsupported API version."
  }
}
```

## Protected endpoints

Protected routes use the version **from the JWT**, not from a request header. You cannot change the contract mid-session — obtain a new token with a different `api_version` at auth time.

## Adding new versions

When a new API version is released:

1. A new entry appears in the docs version switcher (with `Stable` or `Beta` tag as appropriate)
2. Existing integrations on older versions continue to work until deprecated

## Stable releases

When `2026-07-02` graduates from beta to stable, the `ST-Api-Version-Beta` header will no longer be sent for that version. Stable versions will roll out to staging and live environments.