API reference

Base URL

https://api.smolmac.com

Every path in this reference is relative to it and starts with /v1. All requests use HTTPS. A trailing slash on a path is ignored.

Authentication

Send your API key in the Authorization header of every request, as a bearer token.

Authorization: Bearer $SMOL_API_KEY

• A key is smol_live_ or smol_test_ followed by 32 letters and digits. A test key works only on the sample files and is never billed.
• Four requests need no key: GET /v1/capabilities, GET /v1/receipt_keys, GET /v1/openapi.json, and a download through a job's signed download_url.
• Keys are for servers. The API sends no CORS headers, so a web page cannot call it from a browser.

See Authentication for how to create and revoke keys.

Versioning

The API is versioned by date. The current version is 2026-10-01, and it is the only one so far. Every response states the version that answered in a Smol-Version header.

Smol-Version: 2026-10-01

You may send the same header on a request to pin the version your code was written against. A request that names a version the API does not have is refused with 400 unsupported_version. Without the header, the current version answers.

Requests

• JSON bodies. Endpoints that take JSON expect a JSON object of at most 64 KB. Field names are in snake_case. A field the endpoint does not define is refused with 400 bad_request, so a misspelled field fails and is not ignored.
• File bodies. The three direct endpoints take the file itself: as the raw request body, or as a multipart/form-data form. See Compress.
• Options. The same options are used everywhere: as dotted query parameters on a direct request (?image.quality=60), and as a nested JSON object on a job. An unknown option is refused with 400 invalid_options. See Options.
• Methods. A method the path does not support returns status 405. A path that does not exist returns 404 not_found.
• Idempotency. POST /v1/jobs accepts an Idempotency-Key header. See Idempotency.
• Presets. A direct request or a job can name a saved set of options with preset. See Presets.

Responses

• JSON. Field names are in snake_case. A field that does not apply is null. It is not left out.
• Timestamps are ISO 8601 strings in UTC with milliseconds, such as 2026-10-01T12:00:03.118Z. Field names end in _at.
• Sizes are whole numbers of bytes.
• Durations are in seconds. Field names end in _seconds.
• Objects carry an object field that names their kind, such as "job" or "upload".
• Lists have the shape { "object": "list", "data": [...], "has_more": false }.
• Files. A successful direct request, and a download of a job's output, return the file as the body. The details travel in response headers.
• Errors are a status of 400 or above with a JSON body that holds one error object, on every endpoint. See Errors.

Request ids

Every response carries a Smol-Request-Id header, such as req_nawnA3JOXOxTy0iq0T57. An error repeats it in the body as error.request_id. Log it with each call. It is the fastest way for support to find a request.

Object ids

An id is a prefix that names the kind of object, an underscore, and 20 letters and digits.

Endpoints

Direct requests. The file goes in and the result comes back in the same response. For images, PDFs, audio, tables and fonts up to 25 MB.

Uploads and jobs. For larger files, and for all video and office documents.

Webhooks. To be told when a job finishes.

Presets. Named sets of options.

Planning and reporting.

A machine-readable description of all of these, in OpenAPI 3.1, is served at GET /v1/openapi.json. It needs no key, and it may be cached for five minutes.

curl "https://api.smolmac.com/v1/openapi.json" -o smol-openapi.json

Two SDKs wrap these endpoints: TypeScript and Node.js and Python.

Objects

• The result object: what the API did to a file.
• The job object: the state of a job.
• Webhook events: what is sent to your server when a job finishes, and the ping test event.
• Errors: the error object and every error code.