Skip to content

Node.js SDK

Convert files between 240+ formats from Node.js. One call uploads your file, converts it, waits and downloads the result; jobs, webhooks and the format list are there when you need more. Node.js 18+, typed, ESM and CommonJS, no dependencies.

npm ↗GitHub ↗Changelog ↗v0.1.0Node.js 18+ · TypeScriptMIT

Installing

Install it with your package manager. Node.js 18+ · TypeScript.

$ npm install @runconvert/sdk

Initializing

new RunConvert({ apiKey?, baseUrl?, timeout?, maxRetries?, fetch? })

Create one client and reuse it. Without an API key it reads the RUNCONVERT_API_KEY environment variable. Get a key in Dashboard → API Keys, and keep it on your server: never put it in browser or mobile app code.

Example

import { RunConvert } from "@runconvert/sdk";

const rc = new RunConvert(); // reads RUNCONVERT_API_KEY

Parameters

  • apiKeystringYour API key. Defaults to the RUNCONVERT_API_KEY environment variable.
  • baseUrlstringDefaults to https://api.runconvert.com/v3.
  • timeoutnumberMilliseconds per API request. Default 60 000. Uploads and downloads have no limit.
  • maxRetriesnumberRetries for network errors, 429 and 5xx. Default 2.
  • fetchtypeof fetchA custom fetch, for proxies or tests.

Quick start

Convert a file in one call: the SDK uploads it, converts it, waits for the job and saves the result.

Example

Convert a file
import { RunConvert } from "@runconvert/sdk";

const rc = new RunConvert();

const { saved } = await rc.convert("report.docx", { to: "pdf", outDir: "out" });
console.log(saved); // [ 'out/report.pdf' ]
[ 'out/report.pdf' ]

Convert

Convert a file

rc.convert(input, { to, from?, options?, outDir?, filename?, tag?, onUpdate?, timeout? }) → Promise<ConvertResult>

Converts one file in one call: uploads a local file (or imports a URL), converts it, waits for the job and, when an output folder is given, downloads the result. Uses credits.

Example

const { saved } = await rc.convert("report.docx", { to: "pdf", outDir: "out" });
console.log(saved);
[ 'out/report.pdf' ]

Parameters

  • inputstring | Uint8Array | Blob | ReadableStreamA local path, an http(s) URL (imported by RunConvert, nothing to upload), bytes, or a binary file or stream.Required
  • tostringThe target format, e.g. "pdf" or "mp3".Required
  • fromstringThe source format. Read from the file name or URL when left out; needed for bytes or streams without a filename.
  • optionsRecord<string, unknown>Engine options for the conversion, e.g. audioBitrate or image_quality. List them with Formats → engines for a pair.
  • outDirstringSave the results in this folder (created if needed). Without it nothing is downloaded; use the result's files.
  • filenamestringThe file's name when you pass bytes or a stream.
  • tagstringA label to find the job later, e.g. "invoices".
  • onUpdate(job: Job) => voidCalled with the job after every check, e.g. to show progress.
  • timeoutnumberMilliseconds to wait for the job before giving up.

Returns

ConvertResult: { job, files, saved }: the finished job, its result files (filename, url, size) and the local paths when outDir is set.

Jobs

Create a job

rc.jobs.create({ tasks, tag?, metadata? }) → Promise<Job>

Creates a job from named tasks that run in order: import → convert → export. Tasks refer to each other by name in input. The job comes back with its tasks; an upload task carries the upload_url to send your file to.

Example

const job = await rc.jobs.create({
  tag: "merge",
  tasks: {
    a: { operation: "import/url", source_url: "https://example.com/cover.pdf" },
    b: { operation: "import/url", source_url: "https://example.com/body.pdf" },
    merge: { operation: "convert", input: ["a", "b"], input_format: "pdf", output_format: "pdf" },
    export: { operation: "export/url", input: "merge" },
  },
});

Parameters

  • tasksRecord<string, TaskDefinition>Named task definitions. Names use letters, digits, - or _ (up to 64 characters).Required
  • tagstringA label to find the job later, e.g. "invoices".
  • metadataRecord<string, unknown>Your own key-value data, returned with the job and in webhooks.

Returns

The job, with its tasks.

Get a job

rc.jobs.get(id) → Promise<Job>

Gets one job with its tasks: status, credits used, and the result files of its export tasks.

Example

Get a job
const job = await rc.jobs.get("job_01hx4k9m2p7w");
console.log(job.status);
{
  "id": "job_01hx4k9m2p7w",
  "status": "finished",
  "tag": "invoices",
  "credits_used": 2,
  "created_at": "2026-11-16T09:12:04Z",
  "ended_at": "2026-11-16T09:12:09Z",
  "tasks": [
    { "name": "import-1", "operation": "import/direct/upload", "status": "finished" },
    { "name": "convert-1", "operation": "convert", "status": "finished" },
    { "name": "export-1", "operation": "export/url", "status": "finished",
      "result": { "files": [
        { "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
      ] } }
  ]
}

Parameters

  • idstringThe job's ID.Required

Returns

The job, with its tasks.

List jobs

rc.jobs.list({ status?, tag?, page?, perPage?, includeTasks? }) → Promise<Page<Job>>

One page of jobs, newest first, with paging details. Filter by status or tag.

Example

Finished jobs
const page = await rc.jobs.list({ status: "finished", perPage: 20 });
for (const job of page.data) console.log(job.id);
{
  "data": [ { "id": "job_01hx4k9m2p7w", "status": "finished", … } ],
  "meta": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3 }
}

Parameters

  • statusJobStatusOnly jobs with this status: waiting, processing, finished, error or canceled.
  • tagstringA label to find the job later, e.g. "invoices".
  • pagenumberPage number, from 1.
  • perPagenumberJobs per page (max 100).
  • includeTasksbooleanInclude each job's tasks.

Returns

One page: { data: Job[], meta: { page, per_page, total, total_pages } }.

Every job

rc.jobs.all({ status?, tag?, perPage?, includeTasks? }) → AsyncGenerator<Job>

Every job, page by page, so you can loop over all of them without handling pages yourself.

Example

Loop over all jobs
for await (const job of rc.jobs.all({ tag: "invoices" })) {
  console.log(job.id, job.status);
}

Parameters

  • filtersobjectThe same filters as list(), without page.

Wait for a job

rc.jobs.wait(id, { timeout?, onUpdate?, throwOnError?, signal? }) → Promise<Job>

Polls a job until it finishes (every 0.7 s, slowing to 3 s). Fails with the task's code and reason if the job fails, and stops after the timeout if you give one.

Example

const done = await rc.jobs.wait(job.id, { timeout: 5 * 60_000 });
for (const file of Jobs.exportedFiles(done)) await rc.files.download(file, "out");

Parameters

  • idstringThe job's ID.Required
  • timeoutnumberMilliseconds to wait. Throws WaitTimeoutError after it.
  • onUpdate(job: Job) => voidCalled with the job after every check, e.g. to show progress.
  • throwOnErrorbooleanFail when the job ends in error (default). Turn off to get the failed job back instead.
  • signalAbortSignalStop waiting when aborted.

Returns

The finished job.

Cancel a job

rc.jobs.cancel(id) → Promise<Job>

Cancels a job's pending tasks. Credits for tasks that didn't finish are refunded.

Example

Cancel
await rc.jobs.cancel("job_01hx4k9m2p7w");

Parameters

  • idstringThe job's ID.Required

Returns

The canceled job.

Delete a job

rc.jobs.delete(id) → Promise<void>

Deletes a job and its files.

Example

Delete
await rc.jobs.delete("job_01hx4k9m2p7w");

Parameters

  • idstringThe job's ID.Required

Result files

Jobs.exportedFiles(job) → ResultFile[]

The files produced by a finished job's export tasks: file name, a temporary download URL and size.

Example

List results
import { Jobs } from "@runconvert/sdk";

for (const f of Jobs.exportedFiles(job)) console.log(f.filename, f.url);
[
  { "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
]

Parameters

  • jobJobA finished job, with its tasks.Required

Files

Upload a file

rc.files.upload(task, file, filename?) → Promise<void>

Sends a file to an import/direct/upload task before its deadline. Use it with a job you created yourself.

Example

Upload
const upload = job.tasks!.find((t) => t.name === "upload")!;
await rc.files.upload(upload, "image.png");

Parameters

  • taskTask | stringThe upload task from the created job, or its upload URL.Required
  • filestring | Uint8Array | Blob | ReadableStreamA local path, bytes, a Blob or a stream.Required
  • filenamestringThe file's name when you pass bytes or a stream.

Download a result

rc.files.download(file, dir, filename?) → Promise<string>

Saves a result file into a folder, keeping its name, and returns the path. Streams, so big files use little memory.

Example

Download
for (const f of Jobs.exportedFiles(job)) {
  console.log(await rc.files.download(f, "out"));
}
out/report.pdf

Parameters

  • fileResultFile | stringA result file from a job's export task, or its URL.Required
  • dirstringThe folder to save into.Required
  • filenamestringSave under this name instead.

Returns

The saved file's path.

Formats

List formats

rc.operations.list({ category? }) → Promise<OperationsCatalog>

Every input format and what it converts to. Public: no API key needed.

Example

Audio formats
const catalog = await rc.operations.list({ category: "audio" });
console.log(catalog.formats.length);

Parameters

  • categoryCategoryOnly one category: document, image, video, audio, ebook, archive, font, cad, …

Returns

{ categories, formats }

Targets for a format

rc.operations.forInput(input) → Promise<InputFormat>

What one format converts to, with the credit cost of each conversion. Public.

Example

What MP4 converts to
const mp4 = await rc.operations.forInput("mp4");
for (const o of mp4.outputs) console.log(o.format, o.credits);
{
  "format": "mp4",
  "category": "video",
  "outputs": [
    { "format": "mp3", "category": "audio", "engine": "ffmpeg", "credits": 1 },
    { "format": "gif", "category": "image", "engine": "ffmpeg", "credits": 4 },
    …
  ]
}

Parameters

  • inputstringThe input format, e.g. "mp4".Required

Engines for a pair

rc.operations.forPair(input, output) → Promise<PairEngines>

The engines for one conversion and the options its convert task accepts, e.g. bitrate or quality. Public.

Example

MP4 → MP3 options
const pair = await rc.operations.forPair("mp4", "mp3");
for (const opt of pair.engines[0].options) console.log(opt.name);
{
  "input": "mp4",
  "output": "mp3",
  "engines": [
    { "name": "ffmpeg", "credits": 1,
      "options": [
        { "name": "audioBitrate", "type": "string",
          "description": "Target audio bitrate in kbps.",
          "supported_values": ["32k", "48k", "64k", "80k", …] },
        …
      ] }
  ]
}

Parameters

  • inputstringThe input format, e.g. "mp4".Required
  • outputstringThe output format, e.g. "mp3".Required

Account

Credits and team

rc.me() → Promise<Me>

The account, team and credit balance behind the API key.

Example

Credits left
const me = await rc.me();
console.log(me.credits.total_remaining);
{
  "user": { "email": "[email protected]", "full_name": "Ada Lovelace" },
  "team": { "name": "Acme" },
  "credits": { "mode": "wallet", "total_remaining": 4820 }
}

Webhooks

Verify a signature

verifySignature(rawBody, signature, secret) → boolean

Checks that a webhook delivery really came from RunConvert: an HMAC-SHA256 of the raw request body with your webhook secret, compared with the X-RunConvert-Signature header in constant time.

Example

Verify
import { verifySignature } from "@runconvert/sdk";

const ok = verifySignature(
  req.body, // raw body
  req.get("X-RunConvert-Signature"),
  process.env.RUNCONVERT_WEBHOOK_SECRET!,
);

Parameters

  • rawBodystring | Uint8ArrayThe raw request body, exactly as received (not parsed JSON).Required
  • signaturestringThe X-RunConvert-Signature header.Required
  • secretstringYour webhook's signing secret.Required

Parse an event

constructEvent(rawBody, signature, secret) → WebhookEvent

Verifies the signature and parses the event in one step. Fails if the signature is wrong.

Throws when the signature doesn't match: answer 400 and ignore the request. Read the body raw (e.g. express.raw()), not as parsed JSON.

Example

Express
import express from "express";
import { constructEvent } from "@runconvert/sdk";

app.post("/webhooks/runconvert", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = constructEvent(req.body, req.get("X-RunConvert-Signature"), process.env.RUNCONVERT_WEBHOOK_SECRET!);
  } catch {
    return res.sendStatus(400);
  }
  if (event.event === "job.finished") console.log("done", event.job.id);
  res.sendStatus(200);
});
{
  "event": "job.finished",
  "job": { "id": "job_01hx4k9m2p7w", "status": "finished", … }
}

Parameters

  • rawBodystring | Uint8ArrayThe raw request body, exactly as received (not parsed JSON).Required
  • signaturestringThe X-RunConvert-Signature header.Required
  • secretstringYour webhook's signing secret.Required

More

Errors

Every failure is a typed error. The API's code tells you what happened, for example BILLING_INSUFFICIENT_CREDITS, UNAUTHORIZED or INVALID_DATA.

Example

Handle errors
import { RunConvertError, JobFailedError } from "@runconvert/sdk";

try {
  await rc.convert("report.docx", { to: "pdf", outDir: "out" });
} catch (e) {
  if (e instanceof JobFailedError) console.log("conversion failed:", e.task?.reason);
  else if (e instanceof RunConvertError) console.log(e.status, e.code, e.message);
  else throw e;
}
422 BILLING_INSUFFICIENT_CREDITS Insufficient credits.

Error types

  • RunConvertErrorclassThe API said no: .status (HTTP status), .code (e.g. BILLING_INSUFFICIENT_CREDITS), .message.
  • JobFailedErrorclassThe job ended in error: .job, and .task with code, reason and message.
  • WaitTimeoutErrorclasswait() ran past its timeout: .job is the job as last seen.

Retries and timeouts

Network errors, rate limits (429) and server errors (5xx) are retried twice with backoff, honouring Retry-After. Creating a job is only retried when the request never reached the API, so a job is never created twice.

Example

Tune retries
const rc = new RunConvert({ maxRetries: 4, timeout: 30_000 });

Like RunConvert? Set us as a preferred source on Google.

Add to Preferred Sources