HTTP API
Routes
| Method and path | Purpose |
|---|---|
GET /v1/{profile}/file/{path} | Image from a profile's local directory |
GET /v1/{profile}/remote?url=… | Image from an allowlisted HTTPS source |
GET /upload/{path} | Alias, when configured in routes |
HEAD on an image route | Response headers without a body |
GET /health | Process health |
GET /ready | Readiness |
/metrics and /license are available on the separate admin listener. Do not expose them through your public proxy.
Format negotiation
curl --fail -H 'Accept: image/avif,image/webp' -D - http://127.0.0.1:8088/v1/bitrix/file/photo.jpg -o /tmp/zorka-image
The service respects q weights, wildcards and explicit exclusions in Accept. Without the header, it selects WebP. When quality preferences are equal, AVIF takes precedence only when image/avif is explicitly accepted.
HTTPS source
curl --fail --get --data-urlencode 'url=https://images.example.com/photo.jpg' -H 'Accept: image/webp' http://127.0.0.1:8088/v1/remote/remote -o /tmp/zorka-remote.webp
The first remote is the profile name from the configuration example; the second is the route type. That profile must allow the source hostname.
File revisions
Local file routes accept an optional ?v=revision. Unknown and duplicate query parameters are rejected. Paths are decoded once; + remains a plus sign.
Response headers
| Header | Meaning |
|---|---|
Content-Type | Actual response format |
Vary: Accept | The representation depends on format negotiation |
ETag | Representation validator |
X-Image-Cache | Cache layer or bypass |
X-Image-Profile | Selected profile |
X-Image-Stored | Result storage information |
X-Request-ID | Identifier for troubleshooting |
If-None-Match and 304 responses are supported. Keep format variants separate when configuring an external cache.
Original fallback
If a transformation is unsupported, a validated original accepted by the client can be returned with Cache-Control: no-store. The original retains its metadata. Set http.fallback: error to return an error instead.
Fallback never bypasses corrupt-file checks, resource limits or source restrictions.