Versioning & Stability
The Proxio API v1 stability policy. The v1 surface is additive-only, breaking changes require a new major version and 12 months notice via a Sunset date, an RFC 9745 Deprecation header, and a Link rel=deprecation, and every response carries X-Proxio-Api-Version.
The API version lives in the path: the base URL ends in /v1. That version
number is a contract, and this page is the contract text.
Stability policy
Proxio API v1 stability. The
/v1surface makes no breaking changes. Adding a new field, endpoint, event type, error code, or optional parameter is a minor, backward-compatible change and may ship at any time, and clients must ignore unknown fields. Removing or renaming a field, endpoint, or error code, or changing a type or a default, is breaking: it requires a new major version (/v2) and 12 months notice, during which deprecated resources return aSunsetHTTP date header and aDeprecationheader carrying the date the deprecation took effect.
This same policy is embedded in the info.description of the
OpenAPI document, so it travels with any tooling you
generate from the spec.
What this means for your code
- Ignore unknown fields. New fields can appear in any response at any time. Deserialize permissively so a new field never breaks your parser.
- Branch on error
code, notmessage. New error codes are additive. Treat an unrecognizedcodeas a generic failure of its HTTP status class. - New optional parameters and event types are safe. They won't change the behavior of requests that don't use them.
- Nothing is removed or renamed inside v1. If a field or endpoint ever has to
go away, it moves to
/v2with a year of overlap.
Version headers
| Header | On | Meaning |
|---|---|---|
X-Proxio-Api-Version | Every response | The API version serving the request, currently 1. |
X-Proxio-Api-Version is the one header actually on the wire today.
Deprecation, Sunset, and Link are stated policy, not current
behavior: nothing in v1 has ever been deprecated, so nothing emits them yet.
The commitment above is what happens when that changes, and the exact wire
format is worth knowing now, before you're reading it under time pressure:
| Header | Format | Meaning |
|---|---|---|
Deprecation | @<unix-seconds>, e.g. @1735689600 | An RFC 9745 structured-field date: when the resource was declared deprecated. Not the bare string true, that spelling was never standardized and carries no date, the one thing you'd actually need to schedule a migration. |
Sunset | An HTTP-date, e.g. Thu, 01 Jan 2026 00:00:00 GMT | RFC 8594: when it stops working, the end of the 12-month window. Same date format as the standard Date header. |
Link | <https://docs.proxio.net/...>; rel="deprecation" | Points at the migration notes for that specific deprecation. |
All three ride on every response the deprecated resource produces, success,
error, and 204 alike, so a client that only ever sees 4xx from a
deprecated endpoint still gets the clock. There's no code path that sends any
of the three outside an actual deprecation. Once v1 has its first one, treat
their appearance as your migration clock starting: parse Deprecation as a
date, not a boolean, and log all three from day one so it surfaces in your
monitoring well ahead of the Sunset date rather than as an outage on it.
Track changes in the changelog
Additive changes ship continuously and are recorded on the Changelog page, each entry dated and tagged additive. Watch it to pick up new fields, endpoints, and events as they land.
Related pages
Idempotency
Send an Idempotency-Key on Proxio API mutations so retries never double-charge or double-create. Learn the new / replay / conflict / in-progress semantics, which endpoints require the key, the 24-hour TTL, and the Idempotent-Replay header.
Account
Read your Proxio profile, wallet balance, and service totals in one call with GET /account. Includes cURL, Python, and Node.js examples.