API docs

Appearance

On this page

Versioning ​

Workshop's API uses versioning to ensure that as we make updates to the API, your existing integrations continue to work. We use a major.minor versioning scheme, where major version bumps include backwards-incompatible changes, and minor version bumps include only backwards-compatible changes. When a new minor version is released, previous minor versions will continue to work.

Non-breaking changes such as new endpoints, new optional parameters, and new response fields will not change the API version.

This versioning is separate from the /v1 path prefix in the URL. Regardless of the API version you are using, the path prefix will always be /v1.

Current version ​

The latest version is: 1.0

Version Pinning ​

When you create an API key in Workshop, it will be pinned to the latest version at that time. Your pinned API version can be changed at any time by editing the API key in your Workshop settings.

If you need to use a version different than the one set on the API key, you can override the version by setting the Workshop-Version header to the target version. The Workshop-Version header will take precedence over the API key's pinned version.

We recommend all applications set the Workshop-Version header to the version they are using in all requests. This will make the process of upgrading to a new version in the future easier. Once you've verified that your integration continues to work as expected with the new version, you can update the API key's pinned version in your Workshop settings.

Example request ​

bash
$ curl https://app.useworkshop.com/api/v1/campaigns \
 -H "Authorization: Bearer 7c4316a4-9dff-4c8e-9898..."
 -H "Workshop-Version: 1.0"

Upgrading ​

When upgrading to a new version, we recommend setting the Workshop-Version header to the target version on all requests and verifying that your integration continues to work as expected before updating your API key's pinned version.

All changes to the API are documented in the changelog. Please review the changelog for any breaking changes and make the necessary updates to your integration before upgrading.