API Reference

emgr exposes a small HTTP API for resizing and then downloading images. This page is the source of truth for it. There is no OpenAPI spec and no generated client any more — GH #53 deleted openapi.yaml and the codegen pipeline that consumed it, replacing the old query-parameter GET /api/images/resize?... endpoint with an imgproxy-compatible signed URL path (implemented under #27 alongside HMAC signing — see the rationale in ADR 0002). This was a hard cutover: the old query-parameter route is gone, not aliased, and there is nothing left to regenerate a client from.

Base URL

There is no versioned path prefix (no /api/v1) — every route below is relative to the service root, e.g. http://localhost:3000.

The most important divergence from imgproxy: g: is grayscale, not gravity

In imgproxy, g: is the gravity option. In emgr, g: is grayscale — gravity is gr: instead.

This isn't a typo or an oversight; it's a deliberate, recorded decision (ADR 0002, "Amendment 2026-08-20: the g: option collision"). g: was already grayscale in this service before anyone noticed imgproxy uses the same prefix for gravity, and the repository owner chose to keep g: as grayscale rather than break it.

Practical consequence, verified against parse_bool/the g match arm (options.rs:383-386, 731-740): g: here accepts exactly one argument, and it must parse as a boolean (true/false/1/0). Every real imgproxy gravity token (ce, no, so, ea, we, noea, nowe, soea, sowe, sm, obj, objw, or a 3-argument fp:{x}:{y}) fails that boolean parse — so an imgproxy URL that tries to use g: for gravity does not get silently misread into a different, wrong result; it gets rejected with 400 Bad Request. That's a real, verified improvement on the "silently misread" outcome the collision could in principle produce — but it's still a hard migration break, not a compatible fallback: any client library that assumes imgproxy's g: means gravity gets a 400 instead of the anchored crop it expected, and has to be changed to send gr: for gravity while reserving g: for grayscale. If you are migrating from imgproxy and use gravity at all, rewrite g: to gr: first.

Every other short option code below matches imgproxy's own vocabulary.

Endpoints

Resize an image (signed URL)

GET /{signature}/{processing_options}/{plain|base64 source}.{extension}

Fetches the source image, resizes/transforms it, stores the result, and redirects to it (301) — it does not stream the resized bytes back directly (see Download a resized image below).

{signature}

Either:

• A URL-safe base64 (no padding) HMAC-SHA256 signature over salt || {processing_options}/{source}.{extension} — the request path after the signature segment, leading / included, exactly as received on the wire, still percent-encoded — keyed by SIGNING_KEY/SIGNING_SALT (Configuration). Computed as base64url_nopad(HMAC-SHA256(key, salt || signed_path)) (src/modules/signing/verify.rs:9-20) and verified in constant time (verify_signature, src/modules/signing/verify.rs:31-43).
• The literal string unsigned — only accepted when the operator has set ALLOW_UNSIGNED_REQUESTS=true. Refused with 403 otherwise (src/modules/api/resize.rs:90-108).

An invalid, missing, or (when not explicitly allowed) unsigned signature returns 403 Forbidden before the processing-options grammar is parsed at all — an unauthenticated caller never gets parse-error feedback as an oracle (src/modules/api/resize.rs:85-89).

This service fails closed at startup, not per-request. If SIGNING_KEY/SIGNING_SALT are unset (or invalid hex) and ALLOW_UNSIGNED_REQUESTS is not explicitly true, the process refuses to start at all, rather than coming up and serving 403 to every caller (SigningConfig::from_env, src/modules/signing/config.rs:42-68). Signing is the default; unsigned is a local-development escape hatch, never a fallback an operator accidentally ends up running in production.

{processing_options}

Zero or more /-delimited segments, each code:arg1:arg2:.... An unknown option code, wrong argument count, or an out-of-range value returns 400 Bad Request (UrlParseError::UnknownOption / InvalidOptionValue, src/modules/url/mod.rs:39-42).

Simple options

Every option below is parsed in src/modules/url/options.rs; the line range for each match arm is cited so this table can be re-verified against the code later.

Resize type (rs:)

rs:{type}:{width}:{height}

{type} is one of:

An empty type slot (rs::800:600) also defaults to fit. An unrecognised type is rejected with 400, not silently substituted (ResizeType::from_str, src/models/params.rs:113-133; dispatch in src/services/image/handler.rs:1169-1210).

Explicit crop (c:)

c:{width}:{height}[:{gravity_tokens...}]

Crops the decoded, autorotated, trimmed image to {width}x{height} before any resize math runs (process_image_blocking_with_limits, src/services/image/handler.rs:620-666). Each dimension follows a three-way convention (options.rs:810-834, parse_crop_dimension):

• 0 — use the full source dimension on that axis (no crop on that axis).
• >= 1 — absolute pixel size.
• (0, 1) — a fraction of the source dimension on that axis.

An optional trailing gravity anchors the crop within the source image, using the same token vocabulary as gr: below (ce, no, so, ea, we, noea, nowe, soea, sowe, or fp:{x}:{y}). If omitted, the crop inherits whatever gr: sets elsewhere in the URL — order-independent, since resolution happens after the whole URL has been parsed (options.rs:75-80, 591-596).

Gravity (gr:)

gr:{type}
gr:fp:{x}:{y}

Anchors two things: the overflow-crop side of rs:fill/rs:auto, and an explicit c: crop that doesn't name its own gravity. {type} is one of ce (centre, default), no, so, ea, we, noea, nowe, soea, sowe, or fp:{x}:{y} — a focus point, x/y fractions in [0, 1] of the image (options.rs:848-884).

Two divergences from imgproxy, both deliberate:

• This is gr:, not g: — see the callout above.
• Smart/saliency gravity (sm) and object-detection gravity (obj, objw, imgproxy Pro) are rejected with 400, not silently aliased to ce or any other gravity — there is no saliency/object-detection implementation behind them (options.rs:842-847, 879-883; Gravity's doc comment, src/models/params.rs:149-155).
• No x_offset/y_offset nudge on the directional/corner/centre variants. imgproxy lets every gravity type take an extra offset pair; this service only exposes an offset-like mechanism for fp:{x}:{y} (where the fraction is the point) — gr:no:10:20 is rejected, it is not "north, nudged by 10x20" (Gravity's doc comment, src/models/params.rs:141-148).

Watermark (wm: and friends)

wm:{opacity}[:{position}[:{x_offset}[:{y_offset}[:{scale}]]]]
wmu:{base64url-encoded-watermark-url}
wms:{width}:{height}
wmr:{angle}
wmsh:{sigma}

Only image watermarking is implemented — imgproxy's text watermarking has no equivalent here at all (no wmt:/text-drawing option exists in the grammar).

wm: is what actually enables watermarking; every other field below is a modifier that has no effect unless wm: is also present (options.rs:132-138). Composited after resize/rotate/flip/grayscale/blur but before the alpha-flatten/normalise stage, so the watermark's own alpha is correctly composited rather than slipping past it (src/services/image/handler.rs:875-880).

Every trailing slot in wm: may be omitted (a shorter segment) or left blank (wm:0.5::10) to keep its default (options.rs:632-667).

JPEG tuning (jpgo:)

jpgo:{progressive}:{no_subsample}

• progressive (true/false/1/0) — encode JPEG progressively instead of baseline sequential.
• no_subsample — encode chroma at full resolution (4:4:4) instead of this service's default 4:2:2.

Either slot left blank keeps this deployment's configured default (JPEG_PROGRESSIVE/JPEG_NO_SUBSAMPLING, resolved in encode_single_image, src/services/image/handler.rs:1056-1061). imgproxy's remaining four slots (trellis_quant, overshoot_deringing, optimize_scans, quant_table) are not implemented and are rejected with 400 if a third argument or beyond is present — there is no equivalent knob in the mozjpeg encoder this service routes JPEG through.

Trim (t:)

t:{threshold}:{color}:{equal_hor}:{equal_ver}

Removes uniform-colour borders. Always the first geometry operation applied, right after decode/autorotate and before crop/resize (src/services/image/handler.rs:644-653).

• threshold (required) — colour-similarity tolerance, compared as the maximum per-channel (Chebyshev) distance from the target colour. This is a simpler, more predictable metric than imgproxy's own perceptual "smart" trim.
• color (optional hex, no leading #) — the colour to treat as background. Defaults to auto-detecting from the image's own top-left corner pixel — a deliberately simpler stand-in for imgproxy's multi-corner smart detection.
• equal_hor / equal_ver (optional booleans, default false) — when set, the two opposing trim amounts on that axis are clamped to their minimum, so only a symmetric amount is cut.

Padding (pd:)

pd:{top}:{right}:{bottom}:{left}

CSS-shorthand-style cascading fallback, reproducing imgproxy's exact positional-with-fallback parse (options.rs:947-993):

• right falls back to top when omitted/empty.
• bottom falls back to top (not right) when omitted/empty.
• left falls back to right's already-resolved value when omitted/empty.

So pd:10 pads every side by 10, pd:10:20 pads top/bottom 10 and left/right 20, pd:10:20:30 pads top 10, left/right 20, bottom 30 — same as CSS's 1/2/3/4-value shorthand, even though the underlying parse is positional, not a value-count switch. At least the top argument must be present. Applied after ex: (extend), always enlarging the canvas via a background-coloured fill.

Presets (pr:) and the processing-option allowlist

pr:{name}[:{name2}...]

pr: is parsed in src/modules/url/mod.rs (parse_with_config, mod.rs:119-159), not in options.rs like every option above — it's expanded into the option segments it names before ProcessingOptions ever sees them, so it isn't a "code" in the same sense as rs/q/etc.

• PRESETS (env var; imgproxy: IMGPROXY_PRESETS) configures named, reusable option-segment lists: thumbnail=rs:fill:300:300/q:80,default=el:1. See src/modules/url/presets.rs.
• A preset named default is applied automatically ahead of every request's own segments, even when the request never names a preset — overridable by a later explicit option in the same request, since segments apply in order.
• A pr:{name} segment referencing an unknown preset returns 400 (UnknownPreset).
• Presets cannot reference other presets — rejected at config-load time.
• ALLOWED_PROCESSING_OPTIONS (env var; imgproxy: IMGPROXY_ALLOWED_PROCESSING_OPTIONS) is a comma-separated allowlist of option codes permitted directly in a request URL. It does not apply to options used inside a preset's own definition — this is what lets an operator hand out a restricted set of presets while forbidding the raw options they're built from. An option excluded by the allowlist returns 400 (OptionNotAllowed).

See Configuration for how to set both env vars.

Processing pipeline order

Several options interact, and the order they're applied in is not obvious from the URL alone — for example, t: (trim) always runs before c: (crop), and rot:/fl: run after resize, not before. sm: (metadata strip/keep) is not a geometry step at all — it's resolved once at the very top of the encode stage (node N below) and only affects what the chosen encoder writes, not any pixel transform. This is the exact order ImageService applies them in (src/services/image/handler.rs:521-1134):

flowchart TD
    A["Decode source bytes<br/>(DCT-scaled for JPEG — decode_jpeg_scaled,<br/>handler.rs:620-621, 3380-3409)"] --> B["Autorotate<br/>(EXIF Orientation, ar: — handler.rs:639-642)"]
    B --> C["Trim<br/>(t: — handler.rs:650-653)"]
    C --> D["Explicit crop<br/>(c: — handler.rs:663-666)"]
    D --> E["Resize<br/>(rs:/fit/fill/force/auto,<br/>zoom/dpr/enlarge/min-width/min-height —<br/>handler.rs:1169-1210)"]
    E --> F["Rotate<br/>(rot: — handler.rs:1222)"]
    F --> G["Flip<br/>(fl: — handler.rs:1223)"]
    G --> H["Grayscale<br/>(g: — handler.rs:1226-1230)"]
    H --> I["Blur<br/>(bl: — handler.rs:1232-1236)"]
    I --> J["Extend<br/>(ex: — handler.rs:833-844)"]
    J --> K["Padding<br/>(pd: — handler.rs:846-849)"]
    K --> L["Watermark composite<br/>(wm: — handler.rs:875-880)"]
    L --> M["Alpha flatten / normalise<br/>(bg: — handler.rs:906-940)"]
    M --> N["Encode<br/>(q:/fq:/jpgo:/mb:/webpo:/sm:, format from<br/>the URL's .extension — handler.rs:993-1131)"]

Two ordering consequences worth calling out explicitly:

• Because trim runs before crop and crop runs before resize, c:'s width/height are measured against the trimmed image, not the original source.
• Because rot:/fl: run after resize (matching imgproxy's own pipeline), a 90°/270° rotation's effect on which axis gets which requested dimension is already accounted for earlier, in the resize-box calculation itself (effective_resize_box, src/services/image/handler.rs:2685-2829) — the rotation you see here is purely the final pixel rotation.

{plain|base64 source}.{extension}

The trailing .{extension} is mandatory and always determines the output format — it is stripped from whatever precedes it, regardless of what that looks like. Recognised extensions (KNOWN_EXTENSIONS, src/modules/url/source.rs:20):

An unrecognised or missing extension returns 400 (src/modules/url/source.rs:84-97).

AVIF now supports both directions. This service can both produce AVIF output and decode an AVIF source, via libavif — AOM as the AV1 encode backend, dav1d as the decode backend, both compiled from source and statically linked (src/services/image/avif_codec.rs; see that module's own doc comment for why this dependency was chosen over the alternatives evaluated and why SVT-AV1 isn't wired in as a second encode backend). This replaces the pure-Rust ravif/rav1e encoder this service previously shipped — image's own avif/avif-native features are not used for either direction any more (ImageFormat's doc comment, src/models/params.rs).

HEIC is not supported at all — neither as a source nor as an output extension. heic is not in KNOWN_EXTENSIONS, so a .heic request returns 400 before any decode is attempted, and there is no HEIC decoder in this service's dependency tree regardless.

• Base64 form (default): a single URL-safe base64 (no padding) segment encoding the source URL, e.g. aHR0cHM6Ly9leGFtcGxlLmNvbS9waG90by5qcGc.webp decodes to https://example.com/photo.jpg with output format webp.
• Plain form: prefix with plain/ followed by the literal, percent-encoded-where-needed source URL, e.g. plain/https://example.com/photo.jpg.webp — the .webp at the very end is still the grammar's extension, not part of the URL, so the decoded source here is https://example.com/photo.jpg.

A malformed source (missing/unrecognized extension, invalid base64, empty) returns 400 Bad Request.

Worked example

With SIGNING_KEY=6d792d7369676e696e672d6b6579 and SIGNING_SALT=6d792d73616c74 (hex for my-signing-key / my-salt — placeholders only, never use these for anything real), resizing https://images.example.com/photo.jpg to fill 300x300 at quality 80, output JPEG:

GET /de7BKgwO8wFeNZWRWgp3UB9jKwOkVoYM_eMKau2ECgw/rs:fill:300:300/q:80/aHR0cHM6Ly9pbWFnZXMuZXhhbXBsZS5jb20vcGhvdG8uanBn.jpg

(Pinned by a test — src/modules/signing/verify.rs's documented_example module — so this example can't silently drift from what the code actually computes.)

Responses

Download a resized image

GET /api/images/files/{key}

Unchanged from before #53, and deliberately not part of the signed-URL scheme above: it only ever serves bytes already produced and cached by a successful resize, addressed by a content hash that key_validation::validate_cache_key rejects anything malformed against (traversal, absolute paths, wrong shape) — there's no attacker-controlled fetch or CPU cost here to gate with a signature, unlike the resize route.

Downloads a previously-resized image by its cache key (the value of the Location header from a successful resize above — not something you construct by hand). The key is exactly what CacheService::generate_key produces: an optional STORAGE_SUB_PATH prefix followed by a 64-character lowercase hex SHA-256 digest and one of .jpg/.png/.webp/.avif/.gif.

Responses

Health check

GET /health

Returns 200 OK with a plain-text body of OK — not JSON, and no version field. GET / redirects here (307 Temporary Redirect).

Metrics

GET /metrics

Only mounted when the binary is built with --features otel (see src/modules/router/router.rs); absent otherwise. Returns metrics in Prometheus text format.

Requires a bearer token by default. Send Authorization: Bearer {METRICS_AUTH_TOKEN}. A missing or wrong token returns 401 Unauthorized with a WWW-Authenticate: Bearer realm="metrics" header (src/modules/metrics_auth/middleware.rs:50-59) — 401, not 403, since a corrected Authorization header on the same connection can succeed, unlike signed-URL verification. Like signing itself, this fails closed at startup: an otel-featured build with no METRICS_AUTH_TOKEN configured and no explicit ALLOW_UNAUTHENTICATED_METRICS=true refuses to start (MetricsAuthConfig::from_env, src/modules/metrics_auth/config.rs:45-81). See Configuration.

Error response body

Error responses (400/403/401/404/502/503 above) return a plain-text body (content-type: text/plain).