Skip to main content

API versioning

The InboxOps API is versioned by path prefix. The current version is v1.

Current scheme​

  • Base path: All versioned endpoints use the prefix /v1 (e.g. /v1/auth/session, /v1/workspaces/:workspaceId/tickets).
  • Health: The GET /health endpoint is unversioned and may remain stable across API versions.
  • Webhooks: Webhook URLs include the version (e.g. /v1/webhooks/microsoft). When we introduce a new webhook contract, we may add a new path (e.g. /v2/webhooks/...) while keeping v1 for existing subscriptions during a deprecation period.

Backward compatibility within v1​

  • Backward-compatible changes (no new version required): Adding optional request body fields, adding optional query parameters, adding new response fields, adding new endpoints. Clients that ignore unknown fields continue to work.
  • Breaking changes (would require a new version, e.g. v2): Removing or renaming fields or endpoints, changing meaning of existing fields, changing required parameters or auth behavior. We avoid breaking changes within v1; if we need to make them, we will introduce a new version (e.g. /v2/...) and document a migration path and deprecation timeline.

Future versions​

  • If we introduce v2, it will use a new path prefix (e.g. /v2/workspaces/...). v1 will remain available for a documented period. We will announce deprecation and end-of-life in release notes and in the docs.

Changelog and release notes​

  • Product and API changes are summarized in Release notes. Check that page for new features, fixes, and any deprecation notices.