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 MarkdownWhat you can hard-code, and what to read at run time.
Contract: build on it
None of these changes without the process below.
| Contract | Where you read it |
|---|---|
Capability ids, the value you send as capability_id | list_capabilities, GET /capabilities |
Config property names, JSON types, required, default | get_capability_schema, GET /capabilities/{id} |
The set of enum values, const, pattern | the same schema |
Bounds: minimum, maximum, minLength, maxLength, minItems, maxItems | the same schema |
Strictness (additionalProperties: false): an unknown key is refused | every write body, and the estimate |
The deprecated keyword on an old field name | the same schema |
output_kind, category and status values | capability list rows |
Error code values, their retryable verdicts, limit.bound_by values | Errors |
| MCP tool names and their arguments | tools/list on the MCP server |
| REST paths, methods, request and response field names | The OpenAPI document |
CLI command names, flags, --json fields and exit codes | Commands |
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
requiredand ofenumvalues. example_configvalues. The example always validates.- The wording of
message,summary,next_action,charge_summaryandnote. Show them to a person, and branch oncode,retryableand typed fields.
Additive changes ship without warning
These land in any release. A client that follows this table never notices.
| Change | What your client should do |
|---|---|
| A new capability | Read the list at run time. Never hard-code the full catalog. |
| A new optional config field | Nothing. Leave it out and the default applies. |
A new enum value or a wider bound | Nothing. Your old values still validate. |
| A new MCP tool, REST route or query parameter | Nothing. Old ones keep their names. |
| A new field in a response | Ignore 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
| Change | What happens |
|---|---|
| A config field is renamed | The old name keeps working for one minor version, marked deprecated. See below. |
A field or enum value is removed, or a bound narrows | Only when a provider forces it, with a minor version bump. The refusal is invalid_config naming the field. |
| A capability is removed | It leaves the list, and a request for it gets capability_unavailable with capability_status: "retired". |
| A tool, REST field or error code would be renamed | It 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.
"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).
| Where | How to read it |
|---|---|
| MCP | serverInfo.version in the initialize answer from the MCP server |
| REST | info.version in the OpenAPI document |
| Server card | version in the server card |
| CLI | riffads --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. Walkget_capability_schemafor the capabilities you use. - Watch
status. A capability that leaves the list or answerscapability_unavailablewas retired or paused.requires_planmeans the workspace plan changed, not the contract. - Treat
invalid_configas a signal. A config that worked yesterday names the field that moved. Read the schema again rather than retrying.