API upgrades

Your API version controls what parameters you can send in requests and what properties you'll receive in the responses. The version is defined by the API version component of the endpoint. Backward compatible changes in your version are available automatically. To use changes in newer versions, upgrade your API version.


For information about API life cycle and deprecation strategy, see API life cycle and deprecation strategy.

Backward compatible changes

Backward compatible changes are changes to the API that won't break your current implementation. Such changes might speed things up or provide you with new features, but you shouldn't have to do anything to keep things working correctly.

Pismo considers the following changes to be backward compatible.

  • Adding API resources.
  • Adding optional request parameters to existing API methods.
  • Adding properties to existing API responses.

Upgrading your API version

The URL for an endpoint includes the version of the API it uses. For example, in the URL <https://api-sandbox.pismolabs.io/events/v1/timeline>, v1 indicates that it uses version one of the API for that endpoint. For more information on endpoint structure, visit Environments.

If you’re running an older version of an API, you should upgrade to the latest version to take advantage of new functionality or faster, more efficient processing. To see if there are any new API versions available, check out the Pismo Changelog and the latest version of the documentation.

Stay informed with Pismo Changelog

The Pismo Changelog describes changes to the Pismo platform that might affect your implementation, including new features, changes to existing features, and fixed issues. Changelog posts are published at regular intervals and include all changes that have gone live within that interval.

Every changelog post begins with a set of Tags. These are keywords that indicate the topics covered by the changes.

The rest of the post consists of the following sections.

  • Highlights – A list of changes that deliver value to customers.
  • Updates and fixes – A list of smaller changes or bug fixes.

Each section contains one or more entries. An entry consists of the following.

  • Title, which briefly describes the feature that has changed.
  • The description of the change, including links to any relevant documentation.

Subscribe to the Changelog RSS feed

You can use any RSS feed reader to subscribe to the Changelog. For example, to subscribe from Microsoft Outlook, follow these steps.

  1. Right-click the RSS Feeds folder and click Add a New RSS Feed. A new RSS Feed dialog box appears.
  2. Enter the URL of the Pismo Changelog RSS feed. This is the URL of the changelog with .rss appended to the end:
  3. Click Add > OK.

Gmail does not have a similar option for adding an RSS feed. However, Google provides an extension to its Chrome web browser that you can use to link up with the RSS feed tool of your choice. Follow these steps.

  1. In Google Chrome, navigate to RSS Subscription Extension (by Google), and follow the instructions to install the extension.
  2. After installation, enter <https://developers.pismolabs.io/pismo-docs/changelog.rss> in the Chrome address bar and press ENTER. The browser recognizes the URL as an RSS feed and prompts you to select an RSS feed tool.
  3. Follow any instructions provided by the feed reader.