Versioning

The documented external API namespace is:

/api/v1

The older namespace remains available for compatibility:

/api/ext

Policy

• New integrations use /api/v1/*.
• /api/ext/* is compatibility-only and should not be used for new docs or examples.
• Backward-compatible additions can ship inside v1.
• Breaking changes require a new namespace such as /api/v2.
• API documentation and OpenAPI specs must be updated in the same PR as route, scope, payload, response, or error changes.

What Counts as Breaking

• Removing a field from a response.
• Changing a field type.
• Renaming a required request field.
• Changing authentication or scope requirements.
• Returning a materially different status code for an existing case.

What Is Backward Compatible

• Adding optional request fields.
• Adding response fields.
• Adding new endpoints.
• Adding new enum values when clients are expected to ignore unknown values.

Documentation Requirements

Every API change should update:

• endpoint docs under External API;
• apps/docs/public/openapi/whagons-v1.json;
• API Changelog;
• internal implementation notes when the Convex auth, scope, or route model changes.