Jobs

Overview

A job does the same work as a direct request, but in the background. Use one for a file over 25 MB, for any video, and for any Word document, spreadsheet or presentation. You create the job, then wait for it to finish by polling or by webhook, then download the result.

A job is visible only to keys of the account that created it, and only to keys of the same mode. A test key cannot see a job made with a live key.

Create a job

Send a JSON body of at most 64 KB. A field that is not listed here is refused with bad_request, and param names it.

Options

options has one section per kind of file. Only the section for the kind you sent is used. This object shows every option with its default:

{
  "image": {
    "format": "original",
    "quality": 75,
    "resize": { "mode": "fit", "width": 2000, "height": 2000 },
    "strip_metadata": true
  },
  "pdf": { "quality": "medium" },
  "video": {
    "format": "mp4",
    "codec": "h265",
    "quality": "high",
    "resolution": "original",
    "strip_audio": false,
    "slow": false,
    "crf": null,
    "preset": null,
    "audio_quality": "high"
  },
  "audio": {
    "format": "aac",
    "quality": "high",
    "channels": "stereo",
    "strip_metadata": false,
    "bitrate_kbps": null,
    "sample_rate_hz": null
  },
  "convert": { "to": null, "page": 1, "dpi": 144 }
}

• image.resize may be false to keep the image's dimensions.
• Only the five fields shown as null accept null, which means "use the default".
• An unknown section or field, or a value that is not allowed, is refused with invalid_options.
• The image, PDF, audio and convert options are described on the compress and convert pages. Every option is listed in Options.

URL rules

input.url, output.url and webhook_url must each be a public https URL. That means:

• The scheme is https and the port is the default, 443.
• There is no user name or password in the URL.
• The host is a public host name. localhost, single-label names, and names ending in .local, .internal, .lan, .home, .corp, .test, .invalid, .onion or .localhost are refused.
• An IPv6 address is refused. An IPv4 address is accepted only if it is public.

A URL that breaks a rule is refused with 400 bad_request. When an input is fetched, up to three redirects are followed, and each hop must meet the same rules.

Response

Status 202 and the job object, with status: "queued". A response replayed for an idempotency key also carries Smol-Idempotent-Replay: true. A repeat that arrives while the first request is still being handled gets 409 idempotency_in_progress with Retry-After: 1.

{
  "id": "job_7hQ2mVx9KdL4sTn0BwYe",
  "object": "job",
  "livemode": true,
  "operation": "compress",
  "status": "queued",
  "created_at": "2026-10-01T12:00:03.118Z",
  "started_at": null,
  "completed_at": null,
  "progress": { "percent": 0 },
  "input": { "filename": "report.pdf", "size": 48211930 },
  "result": null,
  "error": null,
  "billed": false,
  "expires_at": null,
  "files_deleted": false,
  "metadata": { "order": "1234" }
}

Example

curl -X POST "https://api.smolmac.com/v1/jobs" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2f0e-8f0b-4c53-9d3a-2b7c1c0f5a11" \
  -d '{
    "operation": "compress",
    "input": { "upload": "upl_Zk3q8WcT1nRb5LxYp0Ha" },
    "options": { "pdf": { "quality": "small" } },
    "metadata": { "order": "1234" }
  }'

import { randomUUID } from "node:crypto";

const headers = {
  Authorization: `Bearer ${process.env.SMOL_API_KEY}`,
  "Content-Type": "application/json",
};

const created = await fetch("https://api.smolmac.com/v1/jobs", {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": randomUUID() },
  body: JSON.stringify({
    operation: "compress",
    input: { upload: "upl_Zk3q8WcT1nRb5LxYp0Ha" },
    options: { pdf: { quality: "small" } },
    metadata: { order: "1234" },
  }),
});
if (!created.ok) throw new Error((await created.json()).error.message);
let job = await created.json();

// Poll until the job reaches a final status.
while (job.status === "queued" || job.status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  const response = await fetch(`https://api.smolmac.com/v1/jobs/${job.id}`, { headers });
  if (!response.ok) throw new Error((await response.json()).error.message);
  job = await response.json();
}

if (job.status !== "succeeded") throw new Error(`${job.error.code}: ${job.error.message}`);
console.log(job.result.download_url);

import os, time, uuid
import requests

headers = {"Authorization": f"Bearer {os.environ['SMOL_API_KEY']}"}

created = requests.post(
    "https://api.smolmac.com/v1/jobs",
    headers={**headers, "Idempotency-Key": str(uuid.uuid4())},
    json={
        "operation": "compress",
        "input": {"upload": "upl_Zk3q8WcT1nRb5LxYp0Ha"},
        "options": {"pdf": {"quality": "small"}},
        "metadata": {"order": "1234"},
    },
)
created.raise_for_status()
job = created.json()

# Poll until the job reaches a final status.
while job["status"] in ("queued", "processing"):
    time.sleep(2)
    response = requests.get(f"https://api.smolmac.com/v1/jobs/{job['id']}", headers=headers)
    response.raise_for_status()
    job = response.json()

if job["status"] != "succeeded":
    raise RuntimeError(f"{job['error']['code']}: {job['error']['message']}")
print(job["result"]["download_url"])

The job object

{
  "id": "job_7hQ2mVx9KdL4sTn0BwYe",
  "object": "job",
  "livemode": true,
  "operation": "compress",
  "status": "succeeded",
  "created_at": "2026-10-01T12:00:03.118Z",
  "started_at": "2026-10-01T12:00:04.402Z",
  "completed_at": "2026-10-01T12:00:21.950Z",
  "progress": { "percent": 100 },
  "input": { "filename": "report.pdf", "size": 48211930 },
  "result": {
    "kind": "pdf",
    "input_format": "pdf",
    "output_format": "pdf",
    "original_size": 48211930,
    "output_size": 9310224,
    "savings_percent": 80.7,
    "kept_original": false,
    "increased": false,
    "width": null,
    "height": null,
    "pages": 212,
    "duration_seconds": null,
    "video_codec": null,
    "warnings": [],
    "download_url": "https://api.smolmac.com/v1/jobs/job_7hQ2mVx9KdL4sTn0BwYe/output?expires=1790859621&signature=5f0c2a9e7b3d4c1f8a6e0d2b4c6f8a1e3d5c7b9a0f2e4d6c8b0a1f3e5d7c9b2a",
    "download_expires_at": "2026-10-01T13:00:21.950Z"
  },
  "error": null,
  "billed": true,
  "expires_at": "2026-10-01T13:00:21.950Z",
  "files_deleted": false,
  "metadata": { "order": "1234" }
}

Timestamps are ISO 8601 strings in UTC with milliseconds. Sizes are in bytes.

Status lifecycle

• The usual path is queued, processing, then one of the final statuses. A final status never changes.
• A job can go from processing back to queued if the engine working on it restarts. It is started again on another engine. After three attempts it fails with internal.
• A job that waits more than 30 minutes for a free engine fails with timeout. A job that is processed for more than 4 hours fails with timeout.
• When a job reaches a final status, its input is deleted, billed is set, and a webhook event is sent.
• The job record is kept for 30 days after the job finishes. After that, retrieving the job returns 404. Its entry in the list is removed 30 days after the job was created.

Retrieve a job

Returns status 200 and the job object. Returns 404 not_found if there is no such job, if it belongs to another account, if it was made with a key of the other mode, or if its record has been deleted.

curl "https://api.smolmac.com/v1/jobs/job_7hQ2mVx9KdL4sTn0BwYe" \
  -H "Authorization: Bearer $SMOL_API_KEY"

List jobs

Returns the account's jobs, newest first. A live key lists live jobs. A test key lists test jobs. The list holds the jobs created in the last 30 days.

{
  "object": "list",
  "data": [
    {
      "id": "job_7hQ2mVx9KdL4sTn0BwYe",
      "object": "job",
      "livemode": true,
      "operation": "compress",
      "status": "succeeded",
      "kind": "pdf",
      "error_code": null,
      "billed": true,
      "created_at": "2026-10-01T12:00:03.118Z",
      "completed_at": "2026-10-01T12:00:21.950Z"
    },
    {
      "id": "job_Lp3Xc8VbN1mQw6Zt0RdK",
      "object": "job",
      "livemode": true,
      "operation": "convert",
      "status": "failed",
      "kind": null,
      "error_code": "unsupported_target",
      "billed": false,
      "created_at": "2026-10-01T11:42:50.007Z",
      "completed_at": "2026-10-01T11:42:53.611Z"
    }
  ],
  "has_more": true
}

Each entry is a summary, not the full job object. It has no file name, no result and no download link. Fetch the job by id for those.

To page through the list, pass the id of the last entry as starting_after, and repeat while has_more is true.

curl "https://api.smolmac.com/v1/jobs?limit=50&status=failed&starting_after=job_Lp3Xc8VbN1mQw6Zt0RdK" \
  -H "Authorization: Bearer $SMOL_API_KEY"

Cancel or delete a job

What it does depends on the job's status.

• Queued or processing. The work is stopped. The status becomes canceled, with error.code: "canceled". A job.canceled event is sent. The job is not billed.
• Succeeded, failed or canceled. The status does not change, and no event is sent.
• In every case the input and the stored output are deleted at once, without waiting for expires_at. The download link stops working.

{
  "id": "job_7hQ2mVx9KdL4sTn0BwYe",
  "object": "job",
  "deleted": true
}

deleted refers to the files. The job record stays, so you can still retrieve the job, which now shows files_deleted: true, and fetch its receipt. A file already sent to your own output.url is not affected. Returns 404 not_found under the same conditions as retrieving a job.

curl -X DELETE "https://api.smolmac.com/v1/jobs/job_7hQ2mVx9KdL4sTn0BwYe" \
  -H "Authorization: Bearer $SMOL_API_KEY"

Download the output

Returns the output file of a job that succeeded. There are two ways to authorise the request.

The response has status 200 and the file as its body.

• A signature that does not match, or a link past its expires time, returns 403 invalid_signature.
• 404 not_found is returned when the job has not succeeded, when the output has been deleted, and when the output was sent to your own storage.
• Anyone who has the signed link can download the file until it expires. Treat the link as a secret.

# With the signed link from result.download_url
curl -o report.min.pdf "https://api.smolmac.com/v1/jobs/job_7hQ2mVx9KdL4sTn0BwYe/output?expires=1790859621&signature=5f0c2a9e7b3d4c1f8a6e0d2b4c6f8a1e3d5c7b9a0f2e4d6c8b0a1f3e5d7c9b2a"

# With the API key
curl -o report.min.pdf "https://api.smolmac.com/v1/jobs/job_7hQ2mVx9KdL4sTn0BwYe/output" \
  -H "Authorization: Bearer $SMOL_API_KEY"

Get the receipt

Returns a signed statement of what was processed and when the files were deleted. It is available once the job has a final status. Before that the request is refused with 409 job_not_finished. See Receipts for how to verify one.

{
  "object": "receipt",
  "payload": "{\"version\":1,\"job_id\":\"job_7hQ2mVx9KdL4sTn0BwYe\",\"operation\":\"compress\",\"status\":\"succeeded\",\"standard\":\"v1\",\"input_sha256\":\"3b1f0c9a7d52e84f6a0b9c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5\",\"input_size\":48211930,\"output_sha256\":\"c41d7e0b95a2f3861b7c4d9e0f2a3b5c6d8e7f90a1b2c3d4e5f60718293a4b6c\",\"output_size\":9310224,\"created_at\":\"2026-10-01T12:00:03.118Z\",\"completed_at\":\"2026-10-01T12:00:21.950Z\",\"input_deleted_at\":\"2026-10-01T12:00:21.958Z\",\"output_deleted_at\":\"2026-10-01T13:00:22.104Z\",\"output_delivered_to_customer_storage\":false,\"issued_at\":\"2026-10-01T14:12:09.331Z\"}",
  "signature": "kX9v2mQpL7sT4wZ1aB8cD3eF6gH0jK5nR2uY7xV4bN1mC8qW3eR6tY9uI0oP5aS2dF7gH4jK1lZ8xC3vB6nM0Q==",
  "algorithm": "Ed25519",
  "key_id": "smol-receipt-1"
}

The payload, once parsed, has these fields:

To get a receipt that records the deletion of the output, request it after expires_at or after a DELETE. Receipts can be fetched for 30 days after the job finishes.

Receipt keys

Returns the public keys that receipts are signed with. It needs no API key. To verify a receipt, find the entry whose key_id equals the receipt's, and check the receipt's signature against the UTF-8 bytes of its payload with that public key.

{
  "object": "list",
  "data": [
    {
      "key_id": "smol-receipt-1",
      "algorithm": "Ed25519",
      "format": "spki-base64",
      "public_key": "MCowBQYDK2VwAyEAq8Jm2Yx0v5cT1nRb7LpKd3WzHs9QeFa4UgXo6ViNtB0=",
      "status": "active",
      "retired_at": null
    }
  ],
  "has_more": false
}

The response carries Cache-Control: public, max-age=300. Fetch the keys over HTTPS from api.smolmac.com and store them. Do not take a key from the same place a receipt came from, if that place is not us.

Errors

These are the errors the job endpoints return as HTTP responses. A failure of the work itself is reported on the job, in error. Those codes are listed under job errors.