Skip to main content

​
Base URL, Versioning, and Endpoint Structure

Sorsa API uses URL-based versioning to keep your integrations stable. The version number is part of the base URL, so every request explicitly targets one specific version of the API.

​
Base URL

All requests are made over HTTPS. Plain HTTP is not supported and will be rejected.
Every endpoint path is relative to this base URL. For example, the full URL for fetching a user profile is:

​
Current version: v3

v3 is the current, stable, and recommended version of the Sorsa API. All new endpoints, response fields, and improvements ship under v3.

​
How we version changes

Not every update requires a new version number. Changes fall into two categories.

​
Non-breaking changes (shipped within v3)

These are added to the current version without a version bump. Your existing integrations keep working with no changes on your side:
  • Adding new endpoints
  • Adding new optional query parameters to existing endpoints
  • Adding new fields to JSON response objects
  • Improving error messages or adding more detail to error responses
Because new response fields can be added at any time, parse responses defensively: read the fields you need and ignore any keys you do not recognize, rather than failing when an unexpected field appears.

​
Breaking changes (new version number)

If we ever need to remove response fields, rename parameters, change how authentication works, or alter core endpoint behavior, we release a new version (for example, /v4). When that happens:
  • The previous version stays online during a clearly communicated sunset period
  • A migration guide with field mapping and structural changes is published in advance
  • Deprecation timelines are announced through the dashboard and the documentation

​
Legacy version: v2 (retired)

v2 is deprecated and has been shut down. The scheduled shutdown date was May 1, 2026, and v2 endpoints now return 410 Gone. If you have not migrated yet, move to v3 using the Migration Guide, which maps every renamed field, updated request format, and endpoint change from v2 to v3.

​
Next steps