Skip to main content

API Versioning

Asterwise commits to API stability. Code you write against v1 today will keep working — we don't break customer integrations to ship new features.

Current version​

The current API version is 2026-03-01. Every response carries this version in the Asterwise-Version header:

Asterwise-Version: 2026-03-01

You can use this header to detect when we've shipped a new dated version. We update the version string only when adding new fields, new endpoints, or new optional behaviors — never when removing or changing existing behavior.

URL versioning​

All endpoints live under /v1/. The v1 prefix is part of our stability contract. We will only introduce /v2/ if we need to make a breaking change that cannot be handled through additive evolution under v1. If v2 ever launches:

  • v1 will continue working for at least 12 months after v2 ships
  • The deprecation will be announced via the changelog, the Deprecation HTTP header on v1 responses, and direct email to every active API key holder
  • Migration guides will be published before v2 is recommended

To date there has been no breaking change in v1 and we don't plan one.

What counts as a breaking change​

We will not ship any of these without a new major version:

  • Removing an endpoint
  • Removing a response field
  • Changing a response field's type (e.g. integer to string)
  • Changing the semantic meaning of an existing field
  • Adding a new required request parameter to an existing endpoint
  • Changing an enum value (e.g. renaming lahiri to chitrapaksha)
  • Changing the error code returned for an existing failure mode
  • Changing the HTTP status code for an existing error code

We will ship these freely as non-breaking changes:

  • Adding a new endpoint
  • Adding a new response field (clients must ignore unknown fields)
  • Adding a new optional request parameter
  • Adding a new enum value to an existing enum (clients should handle unknown enums gracefully)
  • Adding new error codes (clients should treat unknown codes as generic failures)
  • Improving accuracy of computed values (within the documented precision)
  • Performance improvements
  • Documentation updates

Every non-breaking change appears in the changelog.

Deprecation policy​

When we need to discourage use of a specific endpoint or field (without removing it), we mark it as deprecated:

  1. The endpoint or field continues working
  2. A Deprecation HTTP header appears on every response from the endpoint
  3. The changelog records the deprecation with the replacement
  4. The endpoint stays available for at least 12 months after deprecation
  5. Active customers using the deprecated endpoint receive direct email notice

We have not deprecated anything in v1 to date.

How to track changes​

Three signals tell you when something has changed:

  1. Asterwise-Version header — Watch for this string changing. New value means new (additive) capabilities are available.
  2. Changelog — Dated, structured record of every change to the API surface.
  3. Deprecation header — Per-endpoint notice that a path or field is being phased out.

For breaking changes specifically (which would be v2), we email every active API key holder and announce on the changelog at least 90 days before v2 becomes the default recommendation.

SDK versioning​

The Python and TypeScript SDKs follow standard semantic versioning. API version 2026-03-01 is supported by:

  • asterwise-python 1.x and later
  • asterwise-typescript 1.x and later

SDK major version bumps follow API major version bumps — if v2 of the API ships, SDK 2.x will target it while SDK 1.x continues targeting v1.