Skip to content
Theme
Upload a photo Upload
Theme
Theme
Upload a photo

Developers

Versioning and changelog

How the API is versioned, what counts as a breaking change, deprecation headers, and every change so far.

On this page
  1. Our promise
  2. Build clients that do not break
  3. What counts as breaking
  4. Changelog
  5. 17 November 2026: developer docs
  6. 17 November 2026: v1 platform
  7. Coming next

The API is versioned in the URL. The current version is v1. Code you write today keeps working: within a version we only add things.

Our promise#

  • Within v1 we only make additive changes: new endpoints, new optional parameters, new fields in responses, new event types, new error codes and new enum values.
  • Breaking changes go to a new version (/v2). Both versions run side by side for at least 12 months.
  • Before an endpoint is retired, its responses carry the Deprecation and Sunset headers, and we email the account owners who use it.
  • Every change to the public API is checked against the committed openapi.json before it ships, so a breaking change cannot slip into v1 by accident.

Build clients that do not break#

  • Ignore fields you do not know. New fields can appear at any time.
  • Handle unknown values in type, status and code fields with a sensible default.
  • Do not depend on the order of fields in JSON, or of events.
  • Treat ids and cursors as opaque strings of any length.

What counts as breaking#

Removing or renaming an endpoint, field, parameter or error code; changing a field's type or meaning; making an optional parameter required; or changing authentication. These only happen in a new major version.

Changelog#

Every change to the public API, newest first.

17 November 2026: developer docs#

  • Full developer docs: quickstart, authentication, sandbox, rate limits, idempotency, errors, pagination, webhooks and credits.
  • No API changes.

17 November 2026: v1 platform#

  • API keys (mx_live_, mx_test_) with scopes, IP allowlists, per-key rate limits and monthly credit caps; roll and revoke.
  • Sandbox mode with a test wallet that refills to 1,000 credits a day.
  • GET /v1/health, GET /v1/balance, GET /v1/ledger.
  • GET, POST and DELETE /v1/webhook-endpoints, and GET /v1/events/{id}.
  • Standard Webhooks signatures, retries over about two days, secret rotation with a 24-hour overlap, test events.
  • Problem Details errors (RFC 9457) with stable codes; Idempotency-Key; RateLimit-* headers.
  • Events sent: webhook.test, api_key.revoked.

Coming next#

  • Uploads, photo sets, background tools and logos, with their webhook events.
  • Official PHP and TypeScript SDKs.

Still stuck? Email [email protected] with what you tried and, for API problems, the request_id.

Type at least 2 letters. Use the arrow keys to move and Enter to open.

    Type at least 2 letters. Use the arrow keys to move and Enter to open.