Changelog

This page records changes to the Esfera Converter API contract. The SDK and the CLI keep their own change logs in their packages.

v1 · September 2026

The first version of the API. Everything below is part of the /v1 contract.

• Conversions. Create a conversion and upload the master with a presigned PUT, or in parallel parts with the multipart calls. Analyse, start, follow, download and delete. List conversions by status with paging.
• Presets and profiles. Four presets (esfera, youtube, bed714_3oa, oa3), and an optional profile on create and start to choose the IAMF profile to declare. GET /v1/presets lists what the encoder accepts.
• Sources. ADM masters, and ambisonic masters of first to third order with an optional source.normalization.
• Webhooks. Up to three active HTTPS endpoints per account, four events (conversion.analyzed, conversion.completed, conversion.failed, conversion.expiring), signed deliveries, a delivery log and replay.
• Usage. GET /v1/usage for minutes, period and limits.
• Errors. RFC 9457 problem documents with stable type URLs.
• Reliability. Idempotency-Key on create, and per-key rate limits with X-RateLimit-* and Retry-After headers.
• The document. GET /v1/openapi.json, an OpenAPI 3.1 description of all of the above.

The versioning promise

/v1 is a contract. Once you have integrated, the shape of requests and responses stays stable. Breaking changes ship as /v2, which runs beside /v1, so you move when you are ready.

Breaking, and so only in a new version: removing or renaming a path, field or enum value; changing a field's type or meaning; making an optional field required; removing a problem type; changing a status code.

Not breaking, and can happen inside /v1: new optional request fields, new response fields, new problem types, and new endpoints. Write clients that ignore fields they do not recognise and treat an unknown problem type as its status code. Read the set of presets and profiles from GET /v1/presets instead of hard-coding it.