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

# Versioning

> How the Matter API is versioned and how to handle upgrades.

The API uses URL path versioning. The current version is `v1`.

## Base URL

```
https://api.getmatter.com/public/v1/
```

The version is part of every endpoint URL:

```
GET  https://api.getmatter.com/public/v1/items
POST https://api.getmatter.com/public/v1/items
GET  https://api.getmatter.com/public/v1/me
```

## Compatibility promise

Within a version, we will **not** make breaking changes. You can rely on:

* Existing fields will not be removed or renamed
* Existing endpoints will not be removed
* Existing error codes will not change meaning
* Response shapes will not change

We **may** add new, non-breaking changes within a version:

* New optional fields on existing resources
* New endpoints
* New optional query parameters
* New error codes for new failure modes

<Tip>
  Write your client code to ignore unknown fields. This ensures you're forward-compatible when we add new response fields.
</Tip>

## Deprecation policy

When we release a new version:

1. The previous version enters a **deprecation period** of at least 6 months
2. Deprecated versions include a `Sunset` header with the retirement date
3. We'll notify you via email before sunsetting a version

```
Sunset: Sat, 01 Nov 2027 00:00:00 GMT
Deprecation: true
```

## Current versions

| Version | Status     | Base URL                               |
| ------- | ---------- | -------------------------------------- |
| `v1`    | **Active** | `https://api.getmatter.com/public/v1/` |