API Versioning
Warning: Unstable API
This project is under active development. Even within v1, breaking changes may occur at any time until a stable release is announced. This notice will be removed once the API is considered stable. You should be able to trust most fields to remain stable, but be prepared for possible changes.
Versioning Scheme
The API uses URL-based versioning with the v1 prefix. All endpoints are prefixed with /v1/.
GET /v1/users/{userID}Version History
| Version | Status | Highlights |
|---|---|---|
| v1 | Current | REST API, WebSocket gateway, documentation |
GET /v1/users/{userID}Stability
Within a major version (e.g. v1), breaking changes are not made. New fields may be added, but existing fields and error shapes remain stable.
Versioning & Compatibility
- Major version in URL (e.g.
/v1/). - Minor/patch releases are non-breaking.
- Breaking changes only in new major versions (v2, v3, ...).
- Deprecated endpoints: marked in docs, supported for at least 6 months.
Upgrading
When upgrading to a new major version:
- Review the changelog and release notes.
- Update clients to ignore unknown fields.
- Ensure error handling supports the canonical envelope.
Guarantees
- New fields may be added at any time.
- Fields are only removed/renamed in major versions.
- Error format: see Error Codes.
Release Cadence
No strict schedule. Patch/minor updates as needed; major versions only for breaking changes.
Release Tagging (CI)
The repository's GitHub Actions workflow for publishing Docker images expects semantic version tags of the form vMAJOR.MINOR.PATCH (for example v1.0.0). The workflow at .github/workflows/docker-publish.yml matches tags using the pattern v*.*.* and uses docker/metadata-action to generate image tags from the semver components ({{version}}, {{major}}.{{minor}}, and {{major}}).
The metadata action therefore produces image tags like 1.0.0, 1.0, and 1 derived from the Git tag, followed by a latest tag that always points to the most recent semver release. API URLs continue to use /v1/; the /v1/ prefix is the stable major version regardless of what the latest Docker image is (for example, a v1.9.12 release can coincide with the latest image).
Examples:
git tag -a v1.0.0 -m "V1.0.0 release"
git push origin main
git push origin v1.0.0Lightweight tags such as v1 do not match the v*.*.* pattern and will not trigger the Docker publish workflow.
Need help?
Open an issue or join the Discord (see README) for migration help.
See also: Changelog, Error Codes, Reference