Guide

Versioning

Atlas public endpoints ship under /v1. The version prefix guarantees stability within a major version. Additive changes — new optional fields, new endpoints, expanded response arrays — stay in v1. Breaking changes require a new major version path and a documented deprecation notice published in the Atlas changelog at least 90 days before sunset of the old version.

Version lifecycle

Stable (GA)Fully supported. Breaking changes require a new major version.
Preview / BetaMay change. Do not use in production traffic without explicit approval.
DeprecatedStill functional but flagged for removal. 90-day notice published in changelog.
SunsetRequests return 410 Gone. Migrate to the current stable version.

What constitutes a breaking change

The following are considered breaking and require a new major version path:

  • Removing or renaming a field in a request or response body
  • Changing the type of an existing field (e.g., string to number)
  • Changing the semantics of a field (e.g., limit as page size vs. offset)
  • Removing an endpoint entirely
  • Making an optional field required
  • Changing authentication or authorization requirements

What is NOT a breaking change

  • Adding new optional fields to request or response bodies
  • Adding new endpoints under the existing version path
  • Expanding the set of values in an enum (without removing existing values)
  • Adding new query parameters to existing endpoints
  • Performance improvements, latency changes, or internal error message rewording

Current version

The current stable version is v1. All Atlas API paths begin with/v1/atlas. Atlas-hosted agents and external agents consume from the same versioned contract.

Base URL: https://api.usemirai.app/v1/atlas
Example paths:
  GET  /v1/atlas/sessions
  POST /v1/atlas/events
  POST /v1/atlas/actions
  GET  /v1/atlas/knowledge
  GET  /v1/atlas/tools/manifest
  GET  /v1/atlas/webhooks

Deprecation policy

When a version or endpoint is deprecated, Mirai publishes a notice in:

  • The Atlas changelog at /developers/changelog
  • The Deprecation and Sunset response headers on affected endpoints
  • Email notification to registered developer contacts for orgs with active integrations

Registered orgs on a deprecated path receive a 90-day grace period before the sunset date. After sunset, affected requests return 410 Gone with a JSON body containing{ "error": "version_unsupported", "migrate_to": "/v1/atlas/..." }.