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
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
v1we 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
DeprecationandSunsetheaders, 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
v1by 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,statusandcodefields 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,POSTandDELETE /v1/webhook-endpoints, andGET /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.