Automation and integration

API keys, batch uploads, and callbacks without guessing the runtime rules.

This page describes the live integration surface: how to authenticate, prepare uploads, poll single jobs or batches, and attach terminal callbacks on the current Pro API path.

Last updated: April 6, 2026

Quickstart

The working flow is intentionally narrow: prepare a job, upload the file to the returned target, then poll or wait for a callback.

1Create an API key in the account area under a Pro account.
2Send POST /uploads/prepare or POST /uploads/batch/prepare with file metadata first.
3Upload the binary to the returned upload target exactly as instructed by the response.
4Poll GET /jobs/:jobId or GET /job-batches/:batchId until the result is ready.
5Optionally add callbackUrl and callbackSecret when you want a terminal push event.

Authentication and access model

Server-to-server requests can authenticate with X-API-Key. Browser session flows use the account session token instead, but the integration model is centered on API keys.

- API keys are created in the account page and are shown in full only once.
- Batch preparation and webhook callbacks are limited to the Pro API path.
- Heavy audio and video jobs still spend media credits from the owner account.
- Single-job status can be checked either with the owning account auth or the signed status token from prepare response.
- Batch status requires the owning account auth and does not expose a public token path.

Headers for authenticated polling

bash

curl https://your-swapmyfile-host.example/jobs/job_123 \
  -H "X-API-Key: smf_live_your_key"

curl https://your-swapmyfile-host.example/jobs/job_123?token=job_status_token

Single job prepare-upload-poll flow

A single job starts with metadata only. The API returns a job record, an upload target, a signed status token, and the next checks that will run after upload is received.

- POST /uploads/prepare validates the request before you transfer the file body.
- The response can return either an API multipart upload target or a direct PUT target plus completeUrl.
- After upload completion, poll GET /jobs/:jobId until status becomes ready or failed.
- When status is ready, use job.downloadUrl for the signed result link.
- callbackUrl and callbackSecret are optional per job and can be attached at prepare time.

Prepare a single job

bash

curl -X POST https://your-swapmyfile-host.example/uploads/prepare \
  -H "Content-Type: application/json" \
  -H "X-API-Key: smf_live_your_key" \
  -d '{
    "converterSlug": "jpg-to-png",
    "inputFilename": "hero.jpg",
    "inputMime": "image/jpeg",
    "inputSize": 245001
  }'

Batch preparation and batch status

Batch preparation lets one API request open multiple upload targets at once. The current backend accepts up to 25 items per batch request and returns both the batch record and per-job upload entries.

- POST /uploads/batch/prepare accepts an optional label and a jobs array.
- Each job still provides its own converterSlug, filename, mime type, size, and optional callback settings.
- Batch labels are limited to 80 characters.
- The public web batch UI keeps a single converter per page, but the API payload is job-by-job.
- Poll GET /job-batches/:batchId with the same owning account auth to track aggregate status.

Prepare a batch request

bash

curl -X POST https://your-swapmyfile-host.example/uploads/batch/prepare \
  -H "Content-Type: application/json" \
  -H "X-API-Key: smf_live_your_key" \
  -d '{
    "label": "April content refresh",
    "jobs": [
      {
        "converterSlug": "jpg-to-png",
        "inputFilename": "hero-01.jpg",
        "inputMime": "image/jpeg",
        "inputSize": 245001
      },
      {
        "converterSlug": "webp-to-png",
        "inputFilename": "hero-02.webp",
        "inputMime": "image/webp",
        "inputSize": 198221
      }
    ]
  }'

Terminal callbacks

Callbacks are designed for the terminal edge of the pipeline, not for every intermediate state. SwapMyFile currently sends callbacks only when a job becomes ready or failed.

- Supported callback events are job.ready and job.failed.
- callbackUrl must be an absolute http or https URL and callbackSecret is optional.
- When callbackSecret is present, the request includes x-swapmyfile-signature with sha256=<hmac> over the raw JSON body.
- The delivery request also includes x-swapmyfile-event and x-swapmyfile-job-id headers.
- A 2xx response marks delivery as successful. Failed deliveries are retried up to 3 times with a short timeout window.

Representative callback payload

json

{
  "event": "job.ready",
  "deliveredAt": "2026-04-06T12:00:00.000Z",
  "job": {
    "jobId": "job_123",
    "converterSlug": "jpg-to-png",
    "status": "ready",
    "inputFilename": "hero.jpg",
    "outputFilename": "hero.png",
    "downloadUrl": "/downloads/signed/example",
    "callback": {
      "url": "https://client.example/hooks/swapmyfile",
      "status": "pending",
      "attempts": 0
    }
  }
}

Integration FAQ

Can a guest session use the API path?

No. Guest users can still use the browser product flow, but API keys, callbacks, and batch preparation are tied to a signed-in Pro account.

Do callbacks replace polling completely?

Not always. Callbacks are useful for terminal state delivery, but polling is still the simpler way to inspect in-progress jobs, batch progress, or download readiness.

Can I still poll a single job without storing account credentials?

Yes. Single-job prepare responses include a signed status token that can be used on GET /jobs/:jobId?token=... for status-only access.

Open the account area before you script against production.

Create the API key, confirm the plan limits on the owning account, and top up media credits first if the workflow includes heavy audio or video jobs.

Open account Review pricing