Skip to main content
This page covers everything enterprise customers need to know about API stability: what version you’re on, what can change without notice, what can’t, how roadmap work lands on top of the stable contract, and how much lead time you’ll get before anything breaks. This page is the customer-facing summary of AtlaSent’s internal versioning doctrine. Where the two differ, the doctrine governs.

​
Current API Version

The current — and only — platform version is AtlaSent v1. All endpoints documented in this reference are served at this version. The version is part of the URL path, so you always know exactly which contract you’re calling. There is no “v2 product” and no “v3 product” on the roadmap. New capabilities ship as additive evolution on v1 — see Roadmap vs. version below.

​
Versioning Scheme

AtlaSent uses URL path versioning. The public HTTP surface is /v1/* and stays /v1/* indefinitely. New endpoints land under /v1/*; they do not introduce /v2/* or /v3/* URL namespaces.
  • The v1 runtime contract — evaluate → permit → verify → execute → audit — has stable semantics. New capabilities extend the contract; they do not redefine it.
  • Minor and patch changes are made in-place within v1 without a URL change. These are always backward compatible (see What “Backward Compatible” Means).
  • A breaking platform version (v2) is a doctrinal exception, not a roadmap milestone, and would require all four of: an unavoidable breaking change, a documented customer-runnable migration plan, a minimum 12-month deprecation runway with both versions operated, and a written compatibility policy for v1-era artifacts. Until those exist, nothing in the roadmap is labeled v2.
You never need to update a URL to receive bug fixes or new optional features.

​
Roadmap vs. version

Roadmap sequencing is separate from the public contract. The roadmap uses phase / wave / pillar vocabulary; it does not use product-generation labels. All three phases ship as v1 additions. The customer-visible contract surface stays v1.

​
Stability Guarantees

Different parts of the API carry different stability commitments. The table below specifies the deprecation notice period you’ll receive before a breaking change or removal. GA endpoints are contractually supported under the MSA / SLA and safe to build critical workflows on. The layered /v1/policy-bundles/* routes are not GA: the production runtime answers them with 501 not_available_on_runtime. Use the legacy /v1-policy-bundles/:id constraint-bundle routes. Beta endpoints are functionally complete but their request/response shapes may change based on customer feedback. Use them with the understanding that a 3-month migration window will be provided. Preview endpoints are early access. They may change at any time with best-effort notice. Do not use them in automated production workflows without consulting your account team.

​
What “Backward Compatible” Means

​
Changes that NEVER happen inside v1

The following changes are considered breaking. AtlaSent will not make them inside v1:
  • Removing an endpoint
  • Renaming a required request field
  • Changing the type of a request or response field
  • Changing authentication requirements for an endpoint
  • Reducing the scope of a valid decision (for example, a response that previously returned allow returning deny under the same inputs)
  • Removing an enum value from a field

​
Changes that MAY happen inside v1 (non-breaking, additive)

The following changes are safe to deploy in-place. Your client must be written to tolerate them:
  • Adding new optional request fields (ignored if your client doesn’t send them)
  • Adding new response fields (your client must not reject unknown fields — avoid strict deserialization that errors on extra keys)
  • Adding new endpoint paths under /v1/*
  • Adding new enum values to extensible fields (your client must handle unknown enum values gracefully — use a default/fallback case)
  • Improved error messages (the error code and HTTP status are stable; the human-readable message text may be refined)
If your client deserializes API responses with strict schema validation that rejects unknown fields, new response fields will break you. Configure your deserializer to ignore unknown fields.

​
Deprecation Policy

When an endpoint or field is deprecated, AtlaSent follows this process:
  1. Announcement: Email to all org admins with affected API keys, a Deprecation response header on the deprecated endpoint, and a changelog entry.
  2. Grace period: The deprecated endpoint continues to work in full for the entire notice period (see stability table above).
  3. Removal: After the notice period expires, the endpoint returns 410 Gone with a JSON body containing a migration_guide_url pointing to the relevant migration documentation.
  4. SDK deprecation: Deprecated SDK methods are annotated with @deprecated JSDoc (TypeScript) or a deprecation docstring (Python). They are removed in the next major SDK version.
Example 410 response body:

​
SDK Compatibility

Per-language SDK majors evolve under standard SemVer rules for that package. They are independent of platform phases and are not platform-version markers. An @atlasent/sdk@2.x is the second major SDK contract generation — a breaking change in SDK ergonomics, wire-call API, or type surface. It is not “AtlaSent v2.” An SDK major version bump may also be triggered by a language ecosystem change (for example, dropping support for an EOL runtime). SDK release notes describe SDK changes; platform release notes describe platform phases; the two cross-reference but never identify.

​
Changelog

All API changes — additions, deprecations, and removals — are published in the Changelog. The changelog is also available at /changelog in this documentation site. Subscribe to changelog notifications in Console → Settings → Notifications.

​
Migration Guides

Inside v1, you do not migrate between platform versions — you opt into new additive capabilities as your tenant flag flips them on. Per-language SDK majors carry their own migration guides under site/sdks/. If a true v2 platform version is ever introduced (subject to the four doctrinal preconditions above), a migration guide will be published with a minimum 12-month overlap window during which both v1 and v2 are operated, deprecation announced at runway start, and v1-era artifacts (permits, audit chains, evidence bundles, signed exports) covered by an explicit compatibility policy.