Every KONVERTER tool,
one API call away.

Overview

The KONVERTER API is a REST API served from https://api.konverterapp.com/v1. It accepts multipart/form-data (to upload files) and JSON, and always answers with JSON. Every operation you can do on konverterapp.com — and every workflow you build — is available to your code.

The API and Workflows are part of the Pro plan. Local tools are free and unlimited (within rate limits); AI tools spend credits from your monthly allowance and top-ups — the same prices as on the website.

Quickstart

1. Create a key on the API keys page and store it as KONVERTER_API_KEY. 2. Convert a file and wait for the result in the same request:

curl -X POST "https://api.konverterapp.com/v1/jobs?wait=true" \
  -H "Authorization: Bearer $KONVERTER_API_KEY" \
  -F operation=image.convert \
  -F format=webp \
  -F file=@photo.heic

3. Browse the operation reference for all 40+ operations and their parameters.

Authentication

Send your key as a bearer token on every request (or as X-API-Key):

Authorization: Bearer kv_live_…

Keys start with kv_live_, are shown once when created and are stored only as a SHA-256 hash — if you lose one, revoke it and create another. You can have up to 10 active keys; revoking takes effect immediately. Keys can’t manage other keys: creating and revoking keys only works from your signed-in account.

Keep keys on your server. Never ship them in browser or mobile code — anyone holding a key can spend your credits.

Errors

Errors use standard HTTP status codes and one JSON shape:

{ "error": { "code": "INVALID_PARAMS", "message": "\"Quality\" must be between 1 and 100" } }

A run that starts but fails reports its error inside the run object (status: "failed", error.code), e.g. INSUFFICIENT_CREDITS, SCANNED_PDF, UNSUPPORTED_FILE, NOT_ENOUGH_FILES, CONVERSION_FAILED, NODE_TIMEOUT, INPUT_DOWNLOAD_FAILED, WEBHOOK_FAILED.

Limits

Rate-limited responses include RateLimit-* headers. Back off and retry on 429 and 5xx.

Credits

Local operations (image, PDF, audio, video and Office tools that run on KONVERTER’s own servers) cost 0 credits. AI operations — background removal, AI enhance / background / expand, advanced OCR, translation, transcription — cost a fixed number of credits per file, shown as credits in GET /v1/operations. Credits come from your monthly allowance first, then your top-up balance.

The balance is checked before each paid step; if it runs out, that step fails with INSUFFICIENT_CREDITS and you are never charged for a step that failed. credits_used on every run shows what it cost.

Jobs

Without wait the API answers 202 immediately with a queued run; with wait=true you get 200 and the finished run (or 202 if it’s still going when the wait times out — then poll it).

# From a URL, JSON body, with a callback
curl -X POST https://api.konverterapp.com/v1/jobs \
  -H "Authorization: Bearer $KONVERTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "operation": "pdf.compress",
        "params": { "level": "high" },
        "file_url": "https://example.com/big-report.pdf",
        "callback_url": "https://example.com/hooks/konverter"
      }'

Runs

{
  "id": "6f1c2e8a-4b7d-4a52-9d2e-1f0c3b5a7e91",
  "object": "run",
  "kind": "job",                  // "job" (one operation) or "workflow"
  "trigger": "api",               // api | manual | webhook | schedule
  "workflow_id": null,
  "status": "succeeded",          // queued | running | succeeded | failed | cancelled
  "progress": 100,
  "created_at": "2026-10-05T09:12:03.120Z",
  "started_at": "2026-10-05T09:12:03.141Z",
  "finished_at": "2026-10-05T09:12:04.007Z",
  "credits_used": 0,
  "nodes": [
    { "id": "step", "type": "image.convert", "label": "Convert image", "status": "succeeded",
      "items_in": 1, "items_out": 1, "item_errors": [], "error": null, "duration_ms": 812, "credits_used": 0 }
  ],
  "outputs": [
    { "id": "9b2f4c1d0e3a", "node_id": "output", "name": "photo.webp", "size": 48211,
      "content_type": "image/webp",
      "url": "https://api.konverterapp.com/v1/runs/6f1c…/outputs/9b2f4c1d0e3a?exp=1791195124&sig=…" }
  ],
  "error": null,                  // { code, message, node_id? } when failed
  "expires_at": "2026-10-05T11:12:04.007Z"
}

Poll every 1–2 seconds until status is succeeded, failed or cancelled — or skip polling with wait=true or a callback_url. Each node reports how many files went in and out; files skipped by a node set to continue on failure are listed in item_errors.

Downloading results

Every output has a ready-to-use url: a signed link that works without your key (handy for passing to another service or a browser) and expires with the run’s results, 2 hours after it finished. The same path also accepts your API key without the signature. After expiry, downloads return 404 — run the job again.

Workflows

Build workflows visually in the editor — they’re instantly callable from the API — or manage them entirely in code:

Saving accepts work-in-progress graphs; the response’s validation lists anything that would stop a run (missing settings, unconnected nodes, loops).

Graph format

A graph is a list of nodes and the edges between them. Files flow along edges as a list: a trigger emits the run’s input files, an operation node processes each file on its own (many-to-one operations like pdf.merge or util.zip combine them), logic nodes route or reshape the list, and output nodes publish the results.

{
  "name": "Web-ready photos",
  "graph": {
    "nodes": [
      { "id": "in",       "type": "input.files" },
      { "id": "resize",   "type": "image.resize",   "params": { "width": 1600, "format": "webp" } },
      { "id": "compress", "type": "image.compress", "params": { "quality": 72 }, "continueOnFail": true },
      { "id": "zip",      "type": "util.zip",       "params": { "filename": "photos-{date}" } },
      { "id": "out",      "type": "output.files" }
    ],
    "edges": [
      { "source": "in",       "target": "resize" },
      { "source": "resize",   "target": "compress" },
      { "source": "compress", "target": "zip" },
      { "source": "zip",      "target": "out" }
    ]
  }
}

Set "continueOnFail": true on a node to skip files it can’t process instead of failing the run. A workflow without any output node returns the files produced by its last steps.

Running workflows

curl -X POST "https://api.konverterapp.com/v1/workflows/WORKFLOW_ID/runs?wait=true" \
  -H "Authorization: Bearer $KONVERTER_API_KEY" \
  -F "files=@invoice-1.pdf" \
  -F "files=@invoice-2.pdf" \
  -F "files=@scan.jpg"

Webhook trigger

Turn on the webhook in the editor (or PATCH { "webhook": true }) to get a secret URL like https://api.konverterapp.com/hooks/w/…. Anyone with the URL can POST files to it to start a run — no API key — which makes it easy to connect Zapier, Make, n8n, forms or other servers. It accepts the same files, file_url and callback_url fields and answers 202 with the run id. Rotate it with { "webhook": "rotate" }, disable it with false. Limit: 30 runs per minute per webhook.

Schedules

Workflows that start with a input.url node can run on a schedule (times in UTC):

PATCH /v1/workflows/:id
{ "schedule": { "enabled": true, "every": "day", "hour": 6, "minute": 30 } }
// every: "hour" (uses minute) | "day" (hour, minute) | "week" (weekday 0=Sun…6, hour, minute)
// "schedule": null removes it

Callbacks & signatures

When a run started with callback_url finishes, we POST { "type": "run.completed", "data": <run> } to it (up to 3 attempts on network errors / 5xx). The output.webhook node sends { "type": "workflow.output", "run_id", "files": [ { name, size, url } ] } — or, in files mode, a multipart body with a payload JSON field plus the files.

Every request carries Konverter-Signature: t=<unix>,v1=<hex> where v1 = HMAC-SHA256(secret, t + "." + body) (for multipart: the payload field). Find your signing secret on the API keys page. Verify it and reject old timestamps:

import crypto from "node:crypto";

// rawBody: the exact request body string (don't re-serialize parsed JSON)
export function verifyKonverter(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= toleranceSec;
  return fresh && expected.length === parts.v1?.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Callback and webhook URLs must be public http(s) addresses — private, loopback and internal networks are refused.

Account

Operation reference

Live from GET /v1/operations. Use the id as operation in a job, or as a node type in a workflow graph.