> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finesse.flamapp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API changelog

> Changes to the Finesse API, and what to update in your integration.

<Update label="October 2026" description="API update" tags={["Action may be needed"]}>
  The URLs, the `X-API-Key` header and your existing keys all keep working: no endpoint was removed,
  and keys created before this update keep full access and don't expire. A few behaviours changed,
  and some of them need a small update on your side.

  ## Check your integration

  These changes can make requests that worked before fail, or return something different.

  <AccordionGroup>
    <Accordion title="Cloning and enrolling require consent" icon="file-signature">
      `POST /voices/clone` and `POST /voices/{id}/enroll` now return `400` unless the form includes
      `consent=true`. Sending it attests that you are the speaker or hold their explicit permission to
      clone their voice, and the attestation is recorded on the voice.

      **Update:** add the form field `consent=true` to clone and enroll requests. See
      [Clone a voice](/voice-api/clone-voice).
    </Accordion>

    <Accordion title="The voice list includes the public catalog" icon="list">
      `GET /voices` returns your workspace's voices first, then the ready public Finesse voices, in
      pages of up to 100. Public voices have `visibility: "public"` and belong to another workspace,
      so updating or deleting one returns `404`.

      **Update:** if you treat the list as "my voices" (for counts, syncing or bulk deletes), keep
      only the voices whose `org_id` is your workspace, and use `page` and `has_more` to page through.
      See [List voices](/voice-api/list-voices).
    </Accordion>

    <Accordion title="Plan limits return 429" icon="gauge">
      Each plan now limits how many syntheses a workspace runs at once (Free 2, Starter 5, Pro 10,
      Enterprise 50). This counts speech, streams and realtime sessions together. The Free plan also
      allows 2 requests per second, including polling. Over a limit, the API returns `429` with
      `code` `concurrency_limited` or `rate_limited` and a `Retry-After` header.

      **Update:** retry `429` responses after `Retry-After` seconds, and reuse a realtime session
      instead of opening several. See [Rate limits](/guides/rate-limits).
    </Accordion>

    <Accordion title="Fewer fields on voices and jobs" icon="filter">
      Voices no longer include `created_by`, `metadata` or `deleted_at`. Clone jobs no longer include
      `engine_id`, `external_job_id`, `idempotency_key`, `params` or `result`.

      **Update:** if you read why a voice failed from `metadata.error`, read the clone job's `error`
      instead (`GET /jobs/{id}`). See the [voice object](/voice-api/voice-object) and
      [Get a job](/voice-api/get-job).
    </Accordion>

    <Accordion title="Engine errors have their own codes" icon="triangle-exclamation">
      When the voice engine is busy, the API returns `503` with `code` `upstream_busy` and a
      `Retry-After` header (it used to pass the engine's `429` through). Text the engine can't use
      returns `422` `invalid_input`, and other engine failures return `502` `upstream_error`. Stream
      `error` events carry the same codes.

      **Update:** branch on the `code` field rather than the status or message, and retry `503`. See
      [Errors](/voice-api/errors).
    </Accordion>

    <Accordion title="Stricter input validation" icon="shield-check">
      These now return `400` instead of being passed to the engine:

      * `output_format` other than `wav`, `s16le`, `s24le`, `s32le`, `f32le` or `f64le` (lower case)
      * `sample_rate` outside 8,000-48,000, `expressiveness` outside 0-1, or `num_step` above 32
      * `ref_text` longer than 4,000 characters

      An upload whose whole request body is over 21 MiB returns `413` `payload_too_large`.

      **Update:** send values within these ranges. See
      [Synthesize parameters](/voice-api/synthesize-parameters).
    </Accordion>

    <Accordion title="Realtime WebSocket follows the documented protocol strictly" icon="bolt">
      * Only the documented message types are accepted: `task_start`, `task_continue`,
        `task_cancel` and `session_end`. Anything else gets a non-fatal `invalid_message` error.
      * Numeric parameters such as `sample_rate` must be JSON numbers, not strings.
      * A single message can be at most 1 MiB; a larger one closes the socket with `1009`.
      * Each open session uses one of your plan's concurrent-synthesis slots; over the limit, the
        handshake gets `429` `concurrency_limited`. When the service is at capacity it gets `503`
        `upstream_busy`. Both come with `Retry-After`.
      * The connection now opens before the engine is reached, and failures close it with a code:
        `1013` when the engine is unavailable, `1008` for insufficient credits, `1011` for other
        errors.

      **Update:** send only the documented messages, and handle the close codes. See
      [Realtime WebSocket](/voice-api/realtime-websocket).
    </Accordion>
  </AccordionGroup>

  ## Added, with nothing to change

  * Errors keep `status`, `error` and `message`, and add a machine-readable `code` and a
    `request_id`. Malformed ids return `404` instead of `500`.
  * Every response has an `X-Request-Id` header; quote it when you contact support.
  * [Short-lived tokens](/voice-api/create-token) (`POST /tokens`) for browsers and devices.
  * Key scopes, expiry and rotation for new keys, in **Settings → API keys**.
  * An `Idempotency-Key` header on create, clone, enroll and speak, so a retry runs at most once.
  * An [OpenAI-compatible speech endpoint](/voice-api/openai-compatible), and voice aliases.
  * The realtime WebSocket also accepts the key in the `X-API-Key` header. The `?api_key=` query
    parameter still works but is deprecated.
</Update>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.