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 the public endpoints (everything in the OpenAPI spec) have had no breaking change in v1, and we don't plan one.

This promise covers those public endpoints. The website's own routes for sign-in, API keys, billing and your account are not part of the public API. They can change when security needs it, and every change is listed in the changelog. For example, on 2026-10-04 an API key stopped being able to manage an account, and the unauthenticated POST /v1/keys was removed.

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

Deprecated so far: GET on five numerology endpoints that put personal data in the URL, replaced by POST with a JSON body (see the changelog).

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 semantic versioning and are at 0.x. Every 0.x release targets API v1 (version 2026-03-01).

  • Patch releases (0.7.0 → 0.7.1) only fix bugs or add things; they never remove or change existing types.
  • Minor releases (0.6 → 0.7) can change generated types, for example a field that becomes required. Each one says exactly what changed in its changelog (Python, TypeScript).

If v2 of the API ships, a new SDK major version will target it, and the current one keeps targeting v1.