Versioning

Mural API follows a simple versioning scheme, using the concept of “major version” only. This means that, once an endpoint is made generally available, we will only make changes to it if the change is non-breaking (additive only).

If we need to make a large change, we’ll do it in a new version. This allows you to trust that your integrations and applications that use these APIs won’t lose functionality due to a breaking change on our end.

The Mural API

Each release of the public Mural API is versioned with a 'v' and an integer, starting at 1. The version increases by 1 for each release. Moving forward, we’ll support 2 versions: the current version and the previous one.

Clients indicate which API version to use by including it in the URL, like https://app.mural.co/api/public/{version}. For example, the v1 URL to get a list of workspaces is https://app.mural.co/api/public/v1/workspaces.

Breaking changes

Changes that remove or change any element or action are considered breaking changes.

Some examples of breaking changes are:

Removing an allowed parameter or a field from a response.
Adding a required parameter or request field without default values.
Changing the field type in a response (for example, changing from a string to a number).
Removing an endpoint.
Changing the HTTP method of an endpoint, or removing HTTP methods from an endpoint.

Non-breaking changes

Not all changes, such as adding functionality, require incrementing the version number.

Some examples of non-breaking changes are:

Adding a field to a response.
Adding a new endpoint.
Adding a new strategy to sort or filter items.
Removing a redundant request header.

New versions

When a new version of the API is released, it is possible that endpoints or capabilities may change. The previous version of the API will remain available for some time, and apps written to use it will continue to work.

As our APIs evolve, Mural will make reasonable efforts to inform you of breaking changes in advance, so you have plenty of time to prepare for any changes that impact your apps.

Enterprise APIs

Mural’s Enterprise APIs follow a similar numbering scheme as the public Mural APIs, but each API increments its version numbers separately.

Preview version

We offer a preview version of APIs so developers can test new endpoints. These shouldn’t be used for production, as we may make changes to the endpoints before the new version is officially released.

You can use preview endpoints by sending the Accept header as vnd.mural.preview in your request.