Staffbase API Versioning

Learn how Staffbase APIs are versioned and how to make the best of them.

Employee App
Staffbase Intranet
Staffbase Email

Staffbase continuously enhances its APIs to keep pace with platform growth, expanding feature sets, and evolving security requirements. Most of these updates are backward compatible, meaning your existing integrations continue to work without any changes. However, in some cases, breaking changes are required. For example, when restructuring a response, renaming fields, or introducing a new pagination method.

In such cases, versioning allows multiple versions of an API to run side by side. This ensures your integration can keep using its current version while you plan and test an update at your own pace. You can then migrate to the latest version while the older one is being deprecated and eventually removed.

In short, versioning enables Staffbase to introduce necessary breaking changes without disrupting your integrations or user experience.

Staffbase APIs are versioned per endpoint at the method level. This means each HTTP method on a given endpoint can be versioned independently. For example, GET /users and POST /users may have different versions. Staffbase uses custom media types specified in the Content-Type header and requests them via the Accept header to differentiate versions.

Each endpoint responds with a media type specific to its domain and entity.

Minimum supported version:

Content-Type: application/json

A breaking change results in a new media type being returned.

Version 1 with custom media type:

Content-Type: application/vnd.staffbase.accessors.user.v1+json

An endpoint can have different versions at different API lifecycle stages. If there are multiple versions, each version is marked with its lifecycle stage, such as beta, production, or deprecated.

Version numbers may not always be sequential. For example, after v1, the next available version could be v3 without a v2 in the headers. But in the documentation, the versions are always listed sequentially for clarity.

To send a request to a specific version of the endpoint, you need to include version information in your request headers. The header information required depends on the type of request:

  • Accept header: Specify the Accept header for the following requests:
    • GET
    • DELETE

Example: Fetch all users from the User API using version Version 2 of the endpoint

curl -X 'GET' \
  'https://exampleapp.staffbase.com/api/users' \
  -H 'Accept: application/vnd.staffbase.accessors.users.v2+json' \
  -H 'Authorization: Basic {API TOKEN}'

  • Accept and Content-Type headers: Specify both Accept and Content-Type headers for the following requests:

    • POST
    • PUT
    • PATCH

The Accept and Content-Type headers may use different media type versions or types because they describe different entities:

  • Accept describes the expected response format.
  • Content-Type describes the format of the data being sent in the request body.

These do not always align in version numbers, since request and response representations can evolve independently.

Example: Invite new users to the platform from the User API using the Version 2 endpoint

curl -X 'POST' \
  'https://exampleapp.staffbase.com/api/users' \
  -H 'Accept: application/vnd.staffbase.accessors.user.v3+json' \
  -H 'Authorization: Basic {API TOKEN}' \
  -H 'Content-Type: application/vnd.staffbase.accessors.user.v2+json' \
  -d '{
  "userName": "janedoe",
  "role": "reader",
  "config": {
    "locale": "en_US"
  }
}'

Latest version recommended
The latest version of an endpoint is recommended for all new and updated integrations, and Staffbase displays it in the API specification by default. You need to manually select the version you require from the API specification.

No header provided
If a client does not include the required header, the API responds with the oldest supported version of the endpoint.

  • This prevents existing integrations from breaking.
  • Integrations continue to work during the deprecation period.

If a client requests an unknown or unsupported media type, the API endpoint returns 406 Not Acceptable