Preset Management

Update a preset — a new version when its steps or subjects change

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
put/api/v1/presets/{slug}

Request

  • Base URL: https://api.imagestep.dev
  • URL: https://api.imagestep.dev/api/v1/presets/{slug}
  • Auth: API key in header Authorization

Path parameters

slugstring required

Preset slug or id

Headers

Idempotency-Keystring

Optional. A client-generated unique key (typically a UUID). Same key + the same request (method, path, query string and body) replays the first response verbatim with Idempotency-Replayed: true, without executing again. Same key + a different one returns 409 idempotency_key_reuse. A repeat that arrives while the first is still running returns 409 request_in_progress, which is retryable. Keys are retained 24 hours. At most 255 characters; a longer one is a 400 invalid_param with param: "Idempotency-Key".

Request body

idstring

Preset id (pre_…; a built-in's starts with builtin-). A job's presetId takes it, the slug, or either with @version.

namestring

Display name (required on create).

slugstring

URL-safe handle, unique per account: lowercase letters, digits and hyphens. Generated from the name when absent (a numeric suffix keeps it unique); one you send must be free. builtin- is reserved.

descriptionstring

Free text for people; not run. "" on a PUT empties it.

versioninteger

Starts at 1 and goes up whenever steps or subjects change; a name, description or slug edit is not a version. Run or read an earlier one as slug@version / ?version=N.

versionCountinteger

How many versions are on record: the current one plus every superseded one. Always present on a read, whether or not versions is, so a list reader can tell a preset with history from one without fetching it.

createdAtstring date-time

When the preset was created

updatedAtstring date-time

When the preset was last saved, a rename included — the order your own rows are listed in. On an earlier version read as slug@N, when that version was saved.

builtInboolean

Whether this is a built-in preset (read-only)

Example request

{
  "name": "Product cut-out, 1200 WebP",
  "slug": "product-cutout",
  "steps": [
    {
      "op": "resize",
      "parameters": {
        "width": 1200,
        "height": 1200,
        "fit": "contain"
      }
    },
    {
      "operation": "sharpen",
      "params": {
        "sigma": 0.5
      }
    },
    {
      "op": "convert",
      "parameters": {
        "format": "webp",
        "quality": 85
      }
    }
  ]
}

Response

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

Changes

No recorded changes to this operation across all 1 revision of this API.