Skip to main content

Versioning and deprecation

This page explains how the InstaVM API changes over time and how you find out before a change can break your integration.

API version​

The API version is part of the path. The current version is v1:

curl https://api.instavm.io/v1/vms \
-H "X-API-Key: $INSTAVM_API_KEY"

A few older endpoints have no version prefix: POST /execute, POST /execute_async, POST /kill, POST /upload and POST /download. They belong to v1 and follow the same rules.

Changes that can ship at any time​

These changes are additive and can ship to v1 without notice:

  • new endpoints
  • new optional request fields and query parameters
  • new fields in responses

Write clients that ignore response fields they do not recognize.

The text of error messages is not part of the contract. Branch on the status code and, where present, on detail.code. See Errors.

Breaking changes​

A breaking change to v1 is announced on the changelog and by email to account owners at least 90 days before it takes effect.

Breaking changes include removing or renaming an endpoint or field, making an optional field required, and changing a field's type.

A change needed to fix a security problem can take effect sooner. It is announced the same way, as soon as it can be.

Deprecated endpoints​

An endpoint you should move off is marked "deprecated": true in the OpenAPI document. These are marked today:

  • POST /v1/sessions/session
  • GET /v1/sessions/session/{session_id}

A deprecated endpoint keeps working. Removing one is a breaking change and gets the notice above. The API does not send Deprecation or Sunset headers.

SDK versions​

The Python SDK (instavm on PyPI) and the TypeScript SDK (instavm on npm) follow semantic versioning. Both are still at 0.x, where a minor release (for example 0.26 to 0.27) may include breaking changes. Pin the minor version:

pip install "instavm~=0.26.0"
npm install instavm@~0.17.0