Docs

Guides

Versioning and changelog

How the API is versioned, what counts as a breaking change, and what changed.

How versioning works#

  • The major version is in the URL: /v1. A breaking change ships under a new major version.
  • Every response carries the behavior version that answered in the X-API-Version header (currently 2026-10-08), and Introspect the API key returns it as api_version.
  • You can pin the behavior version of a request with the optional header Tilt-Pay-Version: 2026-10-08. An unknown value returns 400 unsupported_version. Only one version exists today.

Backward-compatible changes#

These can happen at any time, without a new version. Write your client so that it tolerates them:

  • New endpoints, new optional parameters.
  • New fields in responses and in event payloads: ignore fields you do not know.
  • New error codes and new event types: handle unknown values with a sensible default.
  • New values in an existing enumeration where documented as extensible.

Do not depend on the order of fields, on the format of opaque identifiers or on the text of message.

Changelog#

2026-10-08 (update): webhooks API, profiles, verification and KYC sessions#

  • Webhook endpoints can be managed with the API (/v1/webhook-endpoints, 7 operations). Webhook bodies now carry the same object, created_at and livemode fields as the event log.
  • Users: extended profile (email, first_name, last_name, birth_date, country, referral_code, terms_acceptance, tagname) on create and on the new PATCH /v1/users/{id}; GET /v1/users/{id} returns a UserDetail with the profile; DELETE /v1/users/{id}/profile for erasure. User gains wallet_status, and Wallet gains balance_as_of.
  • Phone verification routes, and POST /v1/users/{id}/kyc-sessions.
  • New error codes, all additive: tagname_already_taken, already_verified, no_pending_verification, invalid_verification_code, verification_expired, verification_attempts_exceeded, live_feature_unavailable, verification_unavailable, feature_unavailable, kyc_session_unavailable, invalid_webhook_url, webhook_endpoint_not_found, webhook_endpoint_exists, webhook_endpoint_limit.

2026-10-08: public API, version 1#

  • Initial release of the public API under /v1: key introspection, users (create, list, retrieve, suspend, unsuspend), wallets (Solana), transactions, KYC status, effective fees, the event log, the sandbox simulator, the published signup flow and Automation Policy evaluation.
  • Signed webhooks for nine event types, with retries, manual replay and secret rotation.
  • Cursor pagination, idempotency keys, per-key rate limits and a uniform error format.
  • An OpenAPI 3.1 specification at GET /v1/openapi.json, which this documentation is generated from.