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

# API Versioning

> How API versioning works in the Turris Public API

# API Versioning

The Turris Public API uses URI-based versioning to ensure backward compatibility while allowing for continuous improvements.

## Version Format

Include the version in your request path:

```
https://public.api.live.turrisfi.com/{version}/endpoint
```

## Available Versions

| Version | Status     | Description                |
| ------- | ---------- | -------------------------- |
| `v1`    | **Stable** | Current production version |

## Using Versions

### Example Request

Use `v1` for all API integrations:

```bash theme={null}
curl -X GET "https://public.api.live.turrisfi.com/v1/agents" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Version Lifecycle

### Stable Versions

* **Backward compatible** - Existing fields and behaviors won't change
* **Additive changes only** - New optional fields may be added
* **Long-term support** - Deprecated with ample notice (minimum 6 months)

## Deprecation Policy

When a version is deprecated:

1. **Announcement** - We'll notify you via email and documentation
2. **Grace period** - Minimum 6 months to migrate
3. **Sunset** - Version returns `410 Gone` after deprecation date

### Deprecation Headers

Deprecated endpoints include warning headers:

```
Deprecation: true
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
Link: <https://docs.turrisfi.com/migration>; rel="deprecation"
```

## Migration Guide

When migrating between versions:

1. **Review changelog** - Check what's changed between versions
2. **Test in sandbox** - Verify your integration works with the new version
3. **Update gradually** - Migrate endpoint by endpoint if needed
4. **Monitor errors** - Watch for issues after migration

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Stable Version" icon="thumbtack">
    Always use the stable version (`v1`) for all integrations
  </Card>

  <Card title="Monitor Headers" icon="bell">
    Watch for deprecation headers in responses
  </Card>

  <Card title="Subscribe to Updates" icon="envelope">
    Stay informed about version changes via our changelog
  </Card>
</CardGroup>