Skip to main content

Base URL and versioning

Base URL​

https://api.aletaplanet.com

Both environments use the same base URL. There is no separate sandbox host. The access token determines which environment a request goes to: at_test_… for sandbox and at_live_… for production. See environments.

All API traffic must use HTTPS. Plain HTTP requests are rejected rather than redirected. This avoids sending credentials over the network before the redirect happens.

TLS 1.2 is the minimum supported version. TLS 1.3 is recommended.

Versioning​

The major API version is part of the URL from the start. This makes it possible to introduce breaking changes later without breaking existing clients.

https://api.aletaplanet.com/v1/cards

Changes that don't require a new version​

The following changes are considered backward-compatible, so your integration should be able to handle them:

  • Adding a new endpoint
  • Adding an optional request parameter
  • Adding a new field to a response
  • Adding a new value to an existing enum
  • Adding a new webhook event type
  • Adding a new error code under an existing error type
  • Changing the wording of a message (the code won't change)
  • Reordering fields in a JSON object

Two things are easy to miss here: new enum values and new webhook event types.

For example, if your code exhaustively handles an enum and throws an error for anything it doesn't recognize, a new enum value could break it. Treat unknown values as unknown instead of treating them as errors.

The same applies to webhook event types: your integration should safely ignore event types it doesn't know about.

Changes that require a new major version​

A new major version is required for changes such as:

  • Removing or renaming an endpoint, field, or enum value
  • Changing a field's type or meaning
  • Making an optional parameter required
  • Changing default behavior in a way that changes existing results
  • Removing a webhook event type

Deprecation policy​

When we deprecate something, we'll:

  1. Announce it in the developer documentation.
  2. Add a Sunset header to responses from the affected endpoint with the removal date, along with a Deprecation: true header.
  3. Publish a migration guide for that specific change.

Minimum notice periods:

ChangeMinimum notice
Endpoint or field removal12 months
Major version end-of-life24 months
Security-driven removalAs short as the risk requires, communicated directly
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jul 2027 23:59:59 GMT
Link: <https://developer.aletaplanet.com/api-reference/conventions/base-urls-and-versioning>;
  rel="deprecation"

If you're only going to monitor one header from this API, make it Sunset.

Optional date-pinned versions​

You can use the Aleta-Version request header to pin behavior to a specific dated release within a major version:

Aleta-Version: 2026-07-28

If you leave the header out, you'll get the current release of that major version.

When you pin a version, you'll still receive additive changes, but behavioral defaults stay the same as they were on the date you pinned.

Last updated on