Presets

Built-in presets first, then your own, most recently updated first. Each entry is the current version — what the preset runs now — and usage, how much it is being run.

NOT PAGED: the built-ins and every preset of yours (an account holds at most 1000) come back in one answer, with no meta.

NO HISTORY BY DEFAULT: versions is left off, and versionCount says how many there are (the current one plus every superseded one). Read one preset's snapshots with GET /api/v1/presets/{slug}, or pass ?includeVersions=true here for the export shape of every preset at once — which is what POST /api/v1/presets/import takes back.

USE THIS WHEN:

• Choosing a preset to run, or listing what an account has saved

DO NOT USE WHEN:

• You know the slug → GET /api/v1/presets/{slug}

FILTER: omit for both, builtin for the shipped ones only, user for your own only.

Every preset the filter selects, built-ins first

Saves version 1 and answers 201 with the preset as saved. Each step is {op, model?, prompt?, parameters?} — an op from GET /api/v1/ops — or {operation, params} — a processing-registry key, for what no op covers. Steps run in order, and they are checked when written, so a preset that saves is one a job can run (the 400s below name the step).

ANSWERS WITH warnings (advisory, the preset is saved): what the steps say that is legal and probably not meant — a format a later step shadows, a step the one before it already did.

NOT REFUSED: an AI step beside other steps, or several AI steps. Such a preset runs as one chain job, each item walking its segments in order (POST /api/v1/jobs).

LIMITS: at most 1000 presets per account, and 50 versions on record per preset (both 422 resource_limit_exceeded); built-ins do not count.

SLUG: generated from the name when absent (a numeric suffix keeps it unique); one you send must be free, lowercase letters, digits and hyphens, and not start with builtin-.

CONSISTENCY (subjects): each subject is {name, referenceAssetIds, descriptor}. The images ride along on the generate / edit step and pin the geometry; the descriptor expands into its prompt wherever you write {{subject.<name>}} (/docs/presets). At most 4 subjects and 4 images across all of them, each your own and DONE; a subject with no images is refused. A name is a handle ([a-z0-9][a-z0-9_-]{0,39}, unique in the preset), a descriptor at most 300 characters.

The preset as saved, with warnings when there is something to say

Takes the list GET /api/v1/presets?filter=user&includeVersions=true returns — without includeVersions the rows carry no history — or any list of preset documents. version and versions are kept as exported (version defaults to 1), so an imported preset replays its history. Each entry is checked like a create; one that fails is reported in errors and the rest still land, so a 201 can carry refusals — read errors. A slug already in use gets a numeric suffix instead of being refused.

LIMITS: the whole import is refused (422 resource_limit_exceeded) if it would take the account past 1000 presets; an entry carrying more than 50 versions is reported in errors and the rest still land.

What landed, and one line per entry that did not

{slug} is a slug or id for the current version, or slug@version for one version — the spelling POST /api/v1/jobs {presetId} and POST /api/v1/images/transform?preset= accept, so what a job ran can always be read back. ?version=N is the same as slug@N; give the version one way, not both.

The response is the export shape: steps, subjects, version and the superseded versions, plus usage over every version. An earlier version comes back with its own steps, subjects and updatedAt (when that version was saved) and without history.

The preset, at the version asked for

Send only what changes: the body is merged over the current preset, and a field it leaves out keeps its value ({"name": "…"} is a whole rename; the slug stays unless you send one). What you do send is checked exactly as on create; "" empties the description. A change to steps or subjects moves the preset to version + 1 and keeps the previous one readable and runnable as slug@version, so a job or automation that pinned a version keeps running exactly that. A name, description or slug edit is not a version. Sending the steps it already has changes nothing. Answers with the preset as saved, and warnings as a create does.

DO NOT USE WHEN:

• Changing a built-in (403) → GET it and POST its steps as your own

The preset as saved — at version + 1 when its steps or subjects changed

Deletes the preset and every version of it; every slug@N a caller holds answers 404 preset_not_found from then on. A job that already ran keeps its own copy of what it ran. Built-ins are 403.

Deleted; no body

Drops slug@version from the preset's history. After it, that reference is 404 preset_not_found for good — nothing else changes: the preset keeps running whatever version it ran, the numbering is untouched (the next version is always current + 1, so a deleted number is never reissued), and a job that ran this version keeps its own copy of what it ran.

USE THIS WHEN:

• A preset is at its version ceiling (422 resource_limit_exceeded on PUT) and you know which earlier versions nothing pins
• A stored version carries a prompt you want gone

DO NOT USE WHEN:

• Anything might still call slug@version — a pinned reference stops resolving, and that is the whole cost of this call

To move what an UNPINNED call runs, PUT the old steps as a new version instead.

Deleted; no body