API guides

Versioning

The major version is in the path: every endpoint lives under /v1. Changes to /v1 are additive only. A breaking change would ship as /v2, with /v1 kept running for 12 months alongside it.

What can change within /v1

• New endpoints and new optional request fields or query parameters.
• New fields in responses and webhook payloads.
• New error codes on existing statuses, and new webhook event types.

Stay compatible

• Ignore response fields you do not know; do not fail on them.
• Handle unknown error codes by their HTTP status (errors).
• Subscribe webhooks to the event types you handle, or ignore unknown types when you use ["*"] (webhooks).

The OpenAPI document and the SDK

The OpenAPI document describes the API as deployed; its info.version (currently 0.1.0) changes with each release. This reference and @upvoiced/sdk are generated from it, so they always match a release; the SDK’s version follows UpVoiced releases.