Stability

What you can build on without it moving, what may change at any time, and how a rename is phased out over one minor version.

Read as Markdown

What you can hard-code, and what to read at run time.

Contract: build on it

None of these changes without the process below.

ContractWhere you read it
Capability ids, the value you send as capability_idlist_capabilities, GET /capabilities
Config property names, JSON types, required, defaultget_capability_schema, GET /capabilities/{id}
The set of enum values, const, patternthe same schema
Bounds: minimum, maximum, minLength, maxLength, minItems, maxItemsthe same schema
Strictness (additionalProperties: false): an unknown key is refusedevery write body, and the estimate
The deprecated keyword on an old field namethe same schema
output_kind, category and status valuescapability list rows
Error code values, their retryable verdicts, limit.bound_by valuesErrors
MCP tool names and their argumentstools/list on the MCP server
REST paths, methods, request and response field namesThe OpenAPI document
CLI command names, flags, --json fields and exit codesCommands

Detail: may change at any time

Never parse or match on these.

  • Every description, label, help text and unit note in a schema.
  • Display names of capabilities, presets, actors and voices.
  • The order of properties, of required and of enum values.
  • example_config values. The example always validates.
  • The wording of message, summary, next_action, charge_summary and note. Show them to a person, and branch on code, retryable and typed fields.

Additive changes ship without warning

These land in any release. A client that follows this table never notices.

ChangeWhat your client should do
A new capabilityRead the list at run time. Never hard-code the full catalog.
A new optional config fieldNothing. Leave it out and the default applies.
A new enum value or a wider boundNothing. Your old values still validate.
A new MCP tool, REST route or query parameterNothing. Old ones keep their names.
A new field in a responseIgnore fields you do not know. Never fail on an extra key.

An estimate is checked exactly like a submit, so it is a free way to test a config.

Breaking changes

ChangeWhat happens
A config field is renamedThe old name keeps working for one minor version, marked deprecated. See below.
A field or enum value is removed, or a bound narrowsOnly when a provider forces it, with a minor version bump. The refusal is invalid_config naming the field.
A capability is removedIt leaves the list, and a request for it gets capability_unavailable with capability_status: "retired".
A tool, REST field or error code would be renamedIt is not. A new one is added beside the old one.

The deprecation window

A renamed field keeps working for one minor version: 1.1.x accepts a name renamed in 1.1.0, and 1.2.0 stops. While it works:

  • The schema lists the old name as optional, with "deprecated": true, no default, and a description naming the new field and the last version.
  • A config with the old name is priced, submitted and deduplicated exactly as if it used the new one.
  • A config with both names is refused with invalid_config. Send only the new one.
Example only: no capability has a deprecated field today
"size": {
  "type": "string",
  "deprecated": true,
  "description": "Deprecated: renamed to image_size. Send image_size instead. size is accepted until version 1.2.0."
}

When you see deprecated: true, switch to the new name in your next release.

Versions

This page describes version 1.2.0, one number for the MCP server and the REST document. The REST path has its own major version (/api/v1).

WhereHow to read it
MCPserverInfo.version in the initialize answer from the MCP server
RESTinfo.version in the OpenAPI document
Server cardversion in the server card
CLIriffads --version. The CLI has its own version number.

The MCP server, the OpenAPI document and the server card:

A minor bump means something was added, or a rename started its window.

1.2.0 rewrote every answer for the person who reads it. A file has one link, url, which never expires. Each answer has a summary. Money is the price before (credits) and the charge after (credits_charged, charge_summary). The hold, the settlement state, the per-unit price lines, the job run id and the second, short link are gone from every answer. No request field, path or error code changed.

How to notice a change

  • Watch the version. A new minor version is the moment to diff.
  • Diff the OpenAPI file. It is built from the same schemas that check requests.
  • Scan for deprecated. Walk get_capability_schema for the capabilities you use.
  • Watch status. A capability that leaves the list or answers capability_unavailable was retired or paused. requires_plan means the workspace plan changed, not the contract.
  • Treat invalid_config as a signal. A config that worked yesterday names the field that moved. Read the schema again rather than retrying.

On this page