API compatibility policy

This policy defines what can change in the Blank Files API and how breaking changes are handled.

Versioning

• Current version: v1.
• Version is part of the URL: /api/v1/....
• Breaking changes require a new major path version.

Stability guarantees (v1)

• Existing endpoints and documented fields remain available within v1.
• Field types and semantics do not change incompatibly.
• New fields may be added; clients should ignore unknown fields.
• API supports conditional requests via ETag and Last-Modified.

Deprecation policy

• Deprecated endpoints remain active for at least 90 days before removal.
• Deprecations are announced in API docs and repository release notes.
• When possible, a direct replacement endpoint is provided.

Rate limits

• Public clients are rate limited by IP.
• Optional API keys may receive higher limits using X-API-Key.
• Heavy clients should use conditional requests to reduce unnecessary traffic.