API Versioning — API Reference | Document Stack Docs

Versioning Scheme

The Document Stack API uses URL-based versioning. The current version is v1, included in every endpoint path:

text

https://api.documentstack.dev/api/v1/generate

When breaking changes are introduced, a new version (e.g., v2) will be released. The previous version will continue to work during the deprecation period.

Stability Guarantees

Within a version, we guarantee:

Existing fields will not be removed or renamed
Request parameters will stay backward-compatible
Error codes and formats will remain consistent
New optional fields may be added to responses (non-breaking)

Adding new fields to a JSON response is considered non-breaking. Make sure your code ignores unknown fields rather than failing on them.

What Counts as a Breaking Change

Change Type	Breaking?
Adding a new optional response field	No
Adding a new optional request parameter	No
Adding a new endpoint	No
Removing or renaming a response field	Yes
Changing a field's data type	Yes
Making an optional parameter required	Yes
Changing error response format	Yes

Deprecation Policy

When a new API version is released:

Announcement — We notify all users via email and the changelog at least 6 months in advance
Overlap period — Both old and new versions run simultaneously for at least 12 months
Sunset — The old version is retired. Requests to the deprecated version return a 410 Gone response with migration instructions

Migration Tips

Always pin your SDK to a specific major version to prevent surprise breaking changes
Use environment variables for the base URL so you can switch API versions without code changes
Test against the new version in a staging environment before upgrading production
Monitor the changelog for deprecation notices

Pinning SDK Version

// package.json — pin to major version
{
  "dependencies": {
    "@document-stack/sdk-node": "^1.0.0"
  }
}

Subscribe to the Document Stack changelog to get notified about new features, deprecations, and version releases.

Next Steps

API Overview — API introduction and authentication
Changelog — Latest API updates
SDK Overview — Official client libraries