Versioning

This page explains how the Wingspan V3 API is versioned and what that means for your client. The short version: the /v3/ in every path is the major version, and you don't need to send anything else today.

The major version is in the URL

Every path starts with /v3/. V1 endpoints (/payments/collaborator, /payments/payable, and so on) are a separate API. See Migrating from V1.

The Wingspan-Version header

The API reads a Wingspan-Version request header. Today it accepts one value, default, and responses echo the version that produced them:

HTTP/1.1 200 OK
Wingspan-Version: default

Omit the header or send Wingspan-Version: default. A request without it is handled as default. Sending any other value, such as a date, returns 422 ValidationError with an UnsupportedValue error on Wingspan-Version. default is the only accepted value.

The version is part of the idempotency fingerprint. If you retry with the same Idempotency-Key but a different Wingspan-Version, you get 409 IdempotencyKeyConflict.

The version of a webhook event's payload is set when the event is created and is carried in the event's apiVersion field. It is a date such as 2026-03-27, set by Wingspan, and it doesn't follow the Wingspan-Version of your requests (which accepts only default). See Webhooks and events.

Write a client that handles additions

Wingspan adds to the V3 API over time: new endpoints, new optional fields, new values in open-ended lists. Build your client so these additions don't break it:

• Ignore response fields you don't recognize. Don't fail when a response has a field your code doesn't know about.
• Don't send fields you haven't read about. Unknown query parameters, filters, and expand values return 422. Many request bodies reject an unknown field with 422 too, but others may ignore it, so check field names against the reference. See Request and response conventions.
• Handle unknown values in open-ended lists. operationType on async operations, detailCode on errors, and webhook event type values grow over time. Keep a default branch for values you don't recognize.
• Branch on code in errors, not on detail text or detailCode. See Errors.
• Treat IDs and page tokens as opaque strings. Don't parse them or depend on their length beyond what the conventions state.

Related pages

• Request and response conventions
• Errors
• Migrating from V1