API reference

Presets

Save a set of options under a name, and apply it to a request with one parameter.

Overview

A preset is a named set of options stored on your account. A request names the preset and gets its options, so the options live in one place and can be changed without a deploy. An account can hold up to 100 presets. They are shared by all of the account's keys, live and test.

Method	Path	Purpose
POST	`/v1/presets`	Create a preset, or replace the one with the same name
GET	`/v1/presets`	List presets
GET	`/v1/presets/{id or name}`	Retrieve a preset
DELETE	`/v1/presets/{id or name}`	Delete a preset

The preset object

json

{
  "id": "pre_Hn4Vx8QtLc1RbZ6sWd0K",
  "object": "preset",
  "name": "web-hero",
  "options": {
    "image": { "format": "avif", "quality": 60, "resize": { "width": 1600 } }
  },
  "created_at": "2026-10-01T09:12:44.031Z",
  "updated_at": "2026-10-01T09:12:44.031Z"
}

Field	Type	Description
id	string	The preset id: pre_ followed by 20 letters and digits.
object	string	Always "preset".
name	string	The name you gave it. Unique within the account.
options	object	The options, exactly as you sent them.
created_at	string	When the preset was created.
updated_at	string	When its options were last replaced.

Create or replace a preset

POST/v1/presets

Send a JSON body. A field that is not listed here is refused with bad_request.

Field	Type	Description
name *	string	1 to 63 characters: lower-case letters, digits, hyphens and underscores. The first character is a letter or a digit.
options *	object	An options object, with the same shape and rules as `options` on a job. It must set at least one option.

bash

curl -X POST "https://api.smolmac.com/v1/presets" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-hero",
    "options": { "image": { "format": "avif", "quality": 60, "resize": { "width": 1600 } } }
  }'

If the account has no preset with that name, one is created. The response has status 201 and the preset object.
If a preset with that name exists, its options are replaced. The response has status 200 and the preset object, with the same id and a new updated_at. Requests that name the preset use the new options from then on.

List presets

GET/v1/presets

Returns every preset of the account, ordered by name. The list is not paginated, so has_more is always false.

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "pre_Hn4Vx8QtLc1RbZ6sWd0K",
      "object": "preset",
      "name": "web-hero",
      "options": {
        "image": { "format": "avif", "quality": 60, "resize": { "width": 1600 } }
      },
      "created_at": "2026-10-01T09:12:44.031Z",
      "updated_at": "2026-10-01T09:12:44.031Z"
    }
  ],
  "has_more": false
}

Retrieve a preset

GET/v1/presets/{id or name}

The last path segment is the preset's id or its name. Returns status 200 and the preset object, or 404 not_found.

bash

curl "https://api.smolmac.com/v1/presets/web-hero" \
  -H "Authorization: Bearer $SMOL_API_KEY"

Delete a preset

DELETE/v1/presets/{id or name}

Deletes the preset. A request that names it afterwards is refused with 400 bad_request. Jobs that were already created keep the options they were created with.

200 OK

{
  "id": "pre_Hn4Vx8QtLc1RbZ6sWd0K",
  "object": "preset",
  "deleted": true
}

Use a preset

Name the preset by its name or its id.

Request	How
Direct request	The `preset` query parameter: `?preset=web-hero`
Job	The `preset` field of the body: `"preset": "web-hero"`

bash

curl -X POST "https://api.smolmac.com/v1/compress?preset=web-hero" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @photo.jpg \
  -o photo.avif

Options sent with the request are applied on top of the preset, field by field. The order, from weakest to strongest, is: the preset, the JSON options of the request, the query string. This request uses the preset but writes WebP:

bash

curl -X POST "https://api.smolmac.com/v1/compress?preset=web-hero&image.format=webp" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @photo.jpg \
  -o photo.webp

A preset may hold options for several kinds of file. Only the section for the kind you send is used.
A preset can supply convert.to, so a convert request can name a preset in place of a target.
The options of a preset are checked again each time it is used, against the rules in force at that time.

Errors

Code	Status	When
`bad_request`	400	Create: the body is not a JSON object, has an unknown field, the name does not match the rule, or options is missing. Use: the request names a preset that the account does not have.
`invalid_options`	400	Create: an option is unknown or has a value that is not allowed, or the options object sets nothing.
`not_found`	404	Retrieve, delete: the account has no preset with that id or name.
`preset_limit_reached`	409	Create: the account already has 100 presets.
`missing_key`, `invalid_key`, `revoked_key`	401	The API key is missing, wrong or revoked.
`no_payment_method`, `payment_required`	402	A live key on an account with no plan, or with an unpaid invoice.
`account_suspended`, `ip_not_allowed`	403	The account is suspended, or the key may not be used from this IP address.