Preset Management

Import presets

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.

post/api/v1/presets/import

Request

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

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

What landed, and one line per entry that did not

Changes

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