Skip to content

API Reference

Convert any file programmatically. Import files, apply conversions, and export results - all in a single API call.

Base URL api.runconvert.com/v3Get API Key
Intro

Overview

The RunConvert API lets you convert any file programmatically. Create jobs with chained tasks - import a file, convert it, and export the result - all in a single request.

Every pipeline follows the same shape: import → convert → export. Tasks reference each other by name using the input field, and the API executes them in dependency order automatically.

Base URL

HTTPShttps://api.runconvert.com/v3

Request format

All request bodies must be JSON. Set Content-Type: application/json on every POST/PATCH request.

Response format

Every response is wrapped: {"success": true, "data": …} on success (lists add a meta object with page, per_page, total and total_pages), and {"success": false, "error": {"code", "message"}} on failure. Object examples below show what's inside data.

Discover supported formats

Call GET /v3/operations (no auth required) to find which input formats are supported, what each can be converted to, and which engines and options are available. See the Discover formats section for full details.

minimal-job.sh
# Convert mp4 → mp3 in one request
curl -X POST https://api.runconvert.com/v3/jobs \
  -H "Authorization: Bearer rc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tasks": {
      "import-1": {
        "operation": "import/url",
        "source_url": "https://example.com/video.mp4"
      },
      "convert-1": {
        "operation": "convert",
        "input": "import-1",
        "input_format": "mp4",
        "output_format": "mp3"
      },
      "export-1": {
        "operation": "export/url",
        "input": "convert-1"
      }
    }
  }'
Intro

Authentication

All API requests require bearer token authentication. Include your API key in the Authorization header of every request.

Never expose API keys in client-side code or public repositories. Use environment variables and keep keys server-side only.

Revoking keys

Revoke any key from Dashboard → API Keys. Revoked keys return 401 immediately.

BASH
curl https://api.runconvert.com/v3/jobs \
  -H "Authorization: Bearer rc_live_..." \
  -H "Content-Type: application/json"
401.json
{
  "success": false,
  "error": {
    "code": "AUTH_INVALID_TOKEN",
    "message": "Invalid or expired token."
  }
}
Intro

Quickstart

Convert an MP4 video to MP3 audio from a public URL in four steps.

01

Import

Define an import/url task pointing at your source file.

02

Convert

Add a convert task. Both input_format and output_format are required.

03

Export

Add an export/url task to get a download link for the output.

04

Poll or webhook

Poll GET /jobs/{id} until status is "finished", or configure a webhook to receive a callback.

Not sure which formats are supported? Call GET /v3/operations?input=mp4 to see all valid output formats for any input extension, along with credit costs.

create-job.sh
curl -X POST https://api.runconvert.com/v3/jobs \
  -H "Authorization: Bearer rc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "mp4-to-mp3",
    "tasks": {
      "import-1": {
        "operation": "import/url",
        "source_url": "https://example.com/video.mp4"
      },
      "convert-1": {
        "operation": "convert",
        "input": "import-1",
        "input_format": "mp4",
        "output_format": "mp3"
      },
      "export-1": {
        "operation": "export/url",
        "input": "convert-1"
      }
    }
  }'
response.json
// 201 Created - tasks are dispatched immediately
{
  "success": true,
  "data": {
    "id": "job_01hx4k9m2p",
    "status": "waiting",
    "tag": "mp4-to-mp3",
    "credits_used": 1,
    "created_at": "2026-05-01T10:23:00Z"
  }
}

// Poll GET /v3/jobs/job_01hx4k9m2p?include=tasks
// until status === "finished"
{
  "success": true,
  "data": {
    "id": "job_01hx4k9m2p",
    "status": "finished",
    "credits_used": 1,
    "started_at": "2026-05-01T10:23:00Z",
    "ended_at":   "2026-05-01T10:23:04Z",
    "expires_at":  "2026-05-02T10:23:04Z",
    "tasks": [
      {
        "name": "export-1",
        "operation": "export/url",
        "status": "finished",
        "result": {
          "files": [{
            "filename": "video.mp3",
            "url": "https://cdn.runconvert.com/dl/...",
            "size": 4821200,
            "created_at": "2026-05-01T10:23:03Z"
          }]
        }
      }
    ]
}}
Core

Jobs

A job is a container for one or more named tasks. Tasks reference each other by name via the input field. The API resolves the dependency graph and executes tasks in the correct order.

Job statuses

waitingJob is queued, waiting for a worker to pick it up
processingOne or more tasks are actively running
finishedAll tasks completed successfully
errorOne or more tasks failed (credits for the tasks that didn't finish are refunded)

Create a job

POST/v3/jobs
ParamTypeDescription
tasksreqobjectNamed task definitions. Keys are task names referenced by downstream tasks via input. Names must be alphanumeric with hyphens or underscores (max 64 chars).
tagstringOptional label for filtering in the list endpoint.
metadataobjectArbitrary key-value data stored with the job.

List jobs

GET/v3/jobs
ParamTypeDescription
filter[status]stringFilter by status: waiting | processing | finished | error
filter[tag]stringFilter by tag.
includestringPass "tasks" to embed task objects in each job.
pageintegerPage number. Default: 1.
per_pageintegerResults per page. Default: 100.

Get a job

GET/v3/jobs/{id}
ParamTypeDescription
includestringPass "tasks" to include task objects in the response.

Cancel a job

POST/v3/jobs/{id}/cancel

Cancels all pending tasks. Credits for the tasks that didn't finish are refunded.

Delete a job

DELETE/v3/jobs/{id}
jobs.sh
# List finished jobs
curl "https://api.runconvert.com/v3/jobs?filter[status]=finished&per_page=10" \
  -H "Authorization: Bearer rc_live_..."

# Get a specific job with its tasks
curl "https://api.runconvert.com/v3/jobs/job_01hx4k9m2p?include=tasks" \
  -H "Authorization: Bearer rc_live_..."

# Cancel a job
curl -X POST https://api.runconvert.com/v3/jobs/job_01hx4k9m2p/cancel \
  -H "Authorization: Bearer rc_live_..."
job-object.json
{
  "id": "job_01hx4k9m2p",
  "status": "finished",
  "tag": "mp4-to-mp3",
  "credits_used": 1,
  "credit_type": "wallet",
  "metadata": {},
  "created_at": "2026-05-01T10:23:00Z",
  "started_at": "2026-05-01T10:23:00Z",
  "ended_at":   "2026-05-01T10:23:04Z",
  "expires_at": "2026-05-02T10:23:04Z"
}
Core

Tasks

Tasks are the individual steps within a job. Each task has an operation plus operation-specific parameters. The input field references the upstream task name - it accepts either a string or an array of strings.

Task statuses

waitingWaiting for upstream tasks to complete
processingCurrently executing
finishedCompleted successfully
errorEncountered an error

ignore_error

Set ignore_error: true on a task to let the job continue even if that task hits an error. Downstream tasks that depend on a failed task are skipped.

List tasks

GET/v3/tasks
ParamTypeDescription
filter[job_id]stringFilter by job ID.
filter[status]stringFilter by status: waiting | processing | finished | error
filter[operation]stringFilter by operation type.
includestringComma-separated extras: retries, payload, depends_on_tasks
pageintegerPage number. Default: 1.
per_pageintegerResults per page. Default: 100.

The /v3/tasks endpoints currently need a signed-in dashboard session; API keys can't call them yet. With an API key, read every task's status and result via GET /v3/jobs/{id}?include=tasks and stop work with POST /v3/jobs/{id}/cancel.

Get / Cancel / Retry a task

GET/v3/tasks/{id}
POST/v3/tasks/{id}/cancel
POST/v3/tasks/{id}/retry

Only tasks in error status can be retried.

task-object.json
{
  "id": "task_9xkq2v",
  "job_id": "job_01hx4k9m2p",
  "name": "convert-1",
  "operation": "convert",
  "status": "finished",
  "percent": 100,
  "message": "",
  "engine": "ffmpeg",
  "engine_version": "6.1",
  "credits": 1,
  "ignore_error": false,
  "input": ["import-1"],
  "result": {
    "files": [{
      "filename": "video.mp3",
      "size": 4821200,
      "url": "https://cdn.runconvert.com/...",
      "created_at": "2026-05-01T10:23:03Z"
    }]
  },
  "created_at": "2026-05-01T10:23:00Z",
  "started_at": "2026-05-01T10:23:00Z",
  "ended_at":   "2026-05-01T10:23:03Z",
  "expires_at": "2026-05-02T10:23:03Z"
}
Import

import/url

Import a file from any publicly accessible URL. RunConvert fetches the file at job execution time.

ParamTypeDescription
operationreqstringMust be "import/url".
source_urlreqstringPublicly accessible http(s) URL of the file to import. The file keeps the name from the URL (or the server's Content-Disposition).
JSON
{
  "tasks": {
    "import-1": {
      "operation": "import/url",
      "source_url": "https://example.com/video.mp4"
    },
    "convert-1": {
      "operation": "convert",
      "input": "import-1",
      "input_format": "mp4",
      "output_format": "mp3"
    }
  }
}
Import

import/direct/upload

Upload a file from your own machine or server. Create the job - the import task in the response carries an upload_url. PUT your file to it, and the job continues automatically once the upload is received.

ParamTypeDescription
operationreqstringMust be "import/direct/upload".

Append &filename=video.mp4 to the upload URL to keep your file name; without it the file is named from its content type. Multipart form uploads also work.

The upload URL expires: upload before the time in the task's upload_deadline.

create-job.json
{
  "tasks": {
    "import-1": { "operation": "import/direct/upload" },
    "convert-1": {
      "operation": "convert",
      "input": "import-1",
      "input_format": "mp4",
      "output_format": "mp3"
    },
    "export-1": { "operation": "export/url", "input": "convert-1" }
  }
}
job-response.json
// POST /v3/jobs?include=tasks - the import task has an upload_url
{
  "success": true,
  "data": {
    "id": "3f2c9a4e-7b1d-4c2a-9e8f-1a2b3c4d5e6f",
    "status": "waiting",
    "tasks": [{
      "name": "import-1",
      "operation": "import/direct/upload",
      "status": "waiting",
      "upload_url": "https://storage.runconvert.com/upload/9b1e...?token=...",
      "upload_deadline": "2026-05-01T10:33:00Z"
    }]
  }
}
upload.sh
# PUT the file to the upload_url (+ &filename= to keep its name)
curl -X PUT "$UPLOAD_URL&filename=video.mp4" \
  --data-binary @video.mp4
# The job continues automatically once the upload is received
Convert

convert

Convert a file from one format to another. Supports 3,000+ format pairs across video, audio, image, document, archive, ebook, font, and CAD categories.

Both input_format and output_format are required. Omitting either returns a 400 error. Use GET /v3/operations?input=mp4 to discover valid output formats for any input extension.

ParamTypeDescription
operationreqstringMust be "convert".
inputreqstringName of the import task whose output to convert.
input_formatreqstringSource format extension, e.g. mp4, png, docx.
output_formatreqstringTarget format extension, e.g. mp3, webp, pdf.
preferred_enginestringRequest a specific engine when multiple are available for this pair. Falls back to the default if not found.
<option name>anyEngine settings go directly on the convert task (not nested), using the exact names from GET /v3/operations?input=X&output=Y - e.g. "audioBitrate": "192k" for mp4 → mp3.
ignore_errorbooleanIf true, the job continues even if this task fails.
const res = await fetch("https://api.runconvert.com/v3/jobs", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.RUNCONVERT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    tasks: {
      "import-1": {
        operation: "import/url",
        source_url: "https://example.com/video.mp4",
      },
      "convert-1": {
        operation: "convert",
        input: "import-1",
        input_format: "mp4",
        output_format: "mp3",
        audioBitrate: "192k",
      },
      "export-1": {
        operation: "export/url",
        input: "convert-1",
      },
    },
  }),
});
const job = await res.json();
console.log(job.id);
Convert

Discover formats

GET /v3/operations is a public endpoint (no auth required) that lets you discover supported formats, valid output targets for any input extension, and the engines and options available for each conversion pair.

GET/v3/operations
ParamTypeDescription
inputstringInput format extension (e.g. mp4). Returns all valid output formats plus credit cost.
outputstringCombined with input - returns available engines and their options for this specific pair.
categorystringFilter all formats by category: video | audio | image | document | ebook | presentation | spreadsheet | vector | cad | archive | font

Using options in a convert task

The engines[].options array tells you what you can pass as the options object on a convert task - including the field name, type, description, and supported values.

BASH
# All output formats for mp4 (no auth needed)
curl "https://api.runconvert.com/v3/operations?input=mp4"

# Engines + options for mp4 → mp3
curl "https://api.runconvert.com/v3/operations?input=mp4&output=mp3"

# All video input formats
curl "https://api.runconvert.com/v3/operations?category=video"

# All formats across all categories
curl "https://api.runconvert.com/v3/operations"
operations-response.json
// GET /v3/operations?input=mp4
{
  "success": true,
  "data": {
    "format": "mp4",
    "category": "video",
    "outputs": [
      { "format": "mp3",  "category": "audio", "engine": "ffmpeg", "credits": 1 },
      { "format": "wav",  "category": "audio", "engine": "ffmpeg", "credits": 1 },
      { "format": "webm", "category": "video", "engine": "ffmpeg", "credits": 3 },
      { "format": "gif",  "category": "image", "engine": "ffmpeg", "credits": 4 }
    ]
  }
}

// GET /v3/operations?input=mp4&output=mp3
{
  "success": true,
  "data": {
    "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", "96k", "128k", "192k", "256k", "320k"]
        },
        {
          "name": "audioCodec",
          "type": "string",
          "description": "Explicit audio codec name or copy.",
          "supported_values": ["aac", "ac3", "mp3", "copy"]
        }
      ]
    }]
  }
}}
Export

export/url

Generate a temporary public download URL for the converted file.

ParamTypeDescription
operationreqstringMust be "export/url".
inputreqstringName of the convert task to export.
archivebooleanIf true, all input files are bundled into one ZIP download.
archive_multiplebooleanBundle into one ZIP only when there is more than one file (every page of a PDF as images: a one-page PDF returns its one image).
archive_namestringThe ZIP's file name, e.g. "report-pages" → report-pages.zip (default export.zip).
export-result.json
// Task definition
{
  "export-1": {
    "operation": "export/url",
    "input": "convert-1"
  }
}

// Result in finished job
{
  "name": "export-1",
  "status": "finished",
  "result": {
    "files": [{
      "filename": "video.mp3",
      "size": 4821200,
      "url": "https://cdn.runconvert.com/dl/abc123/video.mp3",
      "created_at": "2026-05-01T10:23:03Z"
    }]
  }
}
File tools

Compress files

Compressing is a convert task to the file's own format with settings that make it smaller. Images, PNGs, GIFs and PDFs are never returned bigger than they went in: if a file can't shrink, you get the original.

ParamTypeDescription
constant_qualitystringVideo (mp4, mov, mkv, m4v → same): H.264 CRF, higher is smaller. "28" balanced, "32" small. WebM uses VP9's scale: "42" balanced.
resize_videostringVideo: "1080p" | "720p" | "480p".
audioBitratestringMP3 → MP3: "64k" | "96k" | "128k".
image_qualityintegerJPG / WebP → same: 1-100 (72 balanced).
png_qualitystringPNG → PNG: "low" | "medium" | "high" or "60-80" (pngquant; transparency kept).
max_file_sizeintegerJPG: target size in KB (e.g. 100). The photo is scaled down if quality alone can't reach it.
gif_lossy / gif_colorsintegerGIF → GIF: lossy strength 0-200, palette size 2-256. Animation kept.
pdf_compressionstringPDF → PDF: "low" (300 dpi) | "medium" (150 dpi) | "high" (72 dpi).
compress.json
// Compress a PDF
{
  "tasks": {
    "import-0":  { "operation": "import/url", "source_url": "https://example.com/report.pdf" },
    "convert-0": {
      "operation": "convert", "input": ["import-0"],
      "input_format": "pdf", "output_format": "pdf",
      "pdf_compression": "medium"
    },
    "export-0":  { "operation": "export/url", "input": ["convert-0"] }
  }
}

// A JPG under 100 KB
"convert-0": {
  "operation": "convert", "input": ["import-0"],
  "input_format": "jpg", "output_format": "jpg",
  "max_file_size": 100
}
File tools

Merge, split and PDF pages

Merge: give one convert task several inputs. They're joined in the order listed. A task with several inputs is charged once per input (as converting each would be) and takes at most 50.

Split and every page as images return several files; add archive_multiple to the export for one ZIP.

ParamTypeDescription
splitstringPDF → PDF: "pages" (one PDF per page, up to 500) | "ranges".
page_rangesstringWith split "ranges": "1-3, 5, 8-" (8- runs to the last page).
pagesstringPDF → JPG / PNG: "all" renders every page (up to 200); without it, the first page only.
dpiintegerPDF → JPG / PNG with pages all: 36-600 (default 150).
pdf-tools.json
// Merge three PDFs, in this order
{
  "tasks": {
    "a": { "operation": "import/url", "source_url": "https://example.com/cover.pdf" },
    "b": { "operation": "import/url", "source_url": "https://example.com/body.pdf" },
    "c": { "operation": "import/url", "source_url": "https://example.com/appendix.pdf" },
    "merge": {
      "operation": "convert", "input": ["a", "b", "c"],
      "input_format": "pdf", "output_format": "pdf"
    },
    "export": { "operation": "export/url", "input": ["merge"] }
  }
}

// Every page as JPG, one ZIP
"convert-0": { "operation": "convert", "input": ["import-0"],
  "input_format": "pdf", "output_format": "jpg", "pages": "all" },
"export-0":  { "operation": "export/url", "input": ["convert-0"],
  "archive_multiple": true, "archive_name": "report-pages" }
File tools

Images: combine, animate, resize

Several images in one convert task become one PDF (a page each) or one animated GIF (a frame each), in input order.

ParamTypeDescription
page_sizestringImages → PDF: "fit" (default) | "a4" | "letter".
frame_delayintegerImages → GIF: milliseconds per frame, 20-10000 (default 500).
loopbooleanImages → GIF: false plays once (default loops).
width / heightintegerAny image conversion: resize to fit inside this box, proportions kept.
fit_modestring"shrink" only ever makes an image smaller.
images.json
// Three photos into one A4 PDF
"convert-0": {
  "operation": "convert",
  "input": ["import-0", "import-1", "import-2"],
  "input_format": "jpg", "output_format": "pdf",
  "page_size": "a4"
}

// Resize to 1200 px wide
"convert-0": {
  "operation": "convert", "input": ["import-0"],
  "input_format": "png", "output_format": "png",
  "width": 1200
}
File tools

Trim video and audio

Keep the part between two positions in the input. Works on any audio or video conversion, including the same format.

ParamTypeDescription
trim_startstringStart position: seconds ("12.5") or "HH:MM:SS.xxx". Also trimStart.
trim_endstringEnd position in the input (not a length). Also trimEnd.
trim.json
// Keep 0:12 to 0:27 of an MP4
"convert-0": {
  "operation": "convert", "input": ["import-0"],
  "input_format": "mp4", "output_format": "mp4",
  "trim_start": "12", "trim_end": "27"
}
File tools

Extract and create ZIP

Extract: convert an archive to ZIP with extract: true and the files inside come back one by one (up to 500; folders flattened, a repeated name numbered). ZIP, RAR, 7Z, TAR, ISO and more.

Create a ZIP: no convert task: an export with several inputs and archive: true. Nothing is converted, so nothing is charged.

archives.json
// The files inside a RAR
"convert-0": {
  "operation": "convert", "input": ["import-0"],
  "input_format": "rar", "output_format": "zip",
  "extract": true
}

// Any files into one ZIP
{
  "tasks": {
    "a": { "operation": "import/url", "source_url": "https://example.com/a.pdf" },
    "b": { "operation": "import/url", "source_url": "https://example.com/b.jpg" },
    "zip": { "operation": "export/url", "input": ["a", "b"],
             "archive": true, "archive_name": "documents" }
  }
}
Webhooks

Webhooks

Webhooks deliver HTTP POST notifications to your endpoint when jobs and tasks change state - eliminating polling.

Create and manage webhook endpoints in the dashboard under Webhooks. They fire for every job in your team, including jobs created with API keys. The /v3/webhooks endpoints below need a signed-in session; API keys can't call them yet.

Supported events

job.createdA new job was accepted
job.processingThe first task in the job started running
job.finishedAll tasks completed successfully
job.errorOne or more tasks failed (without ignore_error)
task.finishedA single task completed successfully
task.errorA single task failed

Payload structure

Every delivery POSTs JSON with an event string plus either a job or task object depending on the event type.

Signature verification

Every delivery includes an X-RunConvert-Signature header, sha256= followed by the hex HMAC-SHA256 of the raw request body, signed with your webhook secret. Always verify this before processing the payload.

job-event.json
// event: job.finished
{
  "event": "job.finished",
  "job": {
    "id": "job_01hx4k9m2p",
    "status": "finished",
    "tag": "mp4-to-mp3",
    "credits_used": 1,
    "created_at": "2026-05-01T10:23:00Z",
    "ended_at":   "2026-05-01T10:23:04Z",
    "expires_at": "2026-05-02T10:23:04Z"
  }
}
task-event.json
// event: task.finished
{
  "event": "task.finished",
  "task": {
    "id": "task_9xkq2v",
    "job_id": "job_01hx4k9m2p",
    "name": "export-1",
    "operation": "export/url",
    "status": "finished",
    "credits": 0,
    "result": {
      "files": [{
        "filename": "video.mp3",
        "url": "https://cdn.runconvert.com/...",
        "size": 4821200
      }]
    }
  }
}
Webhooks

Create Webhook

POST/v3/webhooks
ParamTypeDescription
urlreqstringHTTPS URL that will receive POST requests.
eventsstring[]Event types to subscribe to. Default: job.finished and job.error.
descriptionstringHuman-readable label for this endpoint.

The full secret is returned once on creation only. Store it securely - subsequent reads return a masked value.

BASH
curl -X POST https://api.runconvert.com/v3/webhooks \
  -H "Authorization: Bearer rc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhooks/runconvert",
    "events": ["job.finished", "job.error"],
    "description": "Production notifications"
  }'
webhook-created.json
{
  "id": "wh_01hx4k9m2p",
  "url": "https://myapp.com/webhooks/runconvert",
  "description": "Production notifications",
  "events": ["job.finished", "job.error"],
  "secret": "whsec_abc123...",
  "enabled": true,
  "created_at": "2026-05-01T10:00:00Z",
  "updated_at": "2026-05-01T10:00:00Z"
}
Webhooks

List & Get Webhooks

GET/v3/webhooks

Returns all webhook endpoints for your account.

GET/v3/webhooks/{id}

Returns a single endpoint. The secret is masked after creation.

Test ping

POST/v3/webhooks/{id}/ping

Sends a test delivery to the endpoint URL to verify it is reachable.

webhook-object.json
{
  "id": "wh_01hx4k9m2p",
  "url": "https://myapp.com/webhooks/runconvert",
  "description": "Production notifications",
  "events": ["job.finished", "job.error"],
  "secret": "whsec_abc***",
  "enabled": true,
  "created_at": "2026-05-01T10:00:00Z",
  "updated_at": "2026-05-01T10:00:00Z"
}
Webhooks

Update Webhook

PATCH/v3/webhooks/{id}

Update any combination of fields. Only provided fields are changed.

ParamTypeDescription
urlstringNew HTTPS endpoint URL.
eventsstring[]Replace the event subscription list.
descriptionstringUpdate the label.
enabledbooleanSet to false to pause delivery without deleting the endpoint.
BASH
# Pause a webhook
curl -X PATCH https://api.runconvert.com/v3/webhooks/wh_01hx4k9m2p \
  -H "Authorization: Bearer rc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

# Change subscribed events
curl -X PATCH https://api.runconvert.com/v3/webhooks/wh_01hx4k9m2p \
  -H "Authorization: Bearer rc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "events": ["job.finished", "job.error", "task.error"] }'
Webhooks

Delete Webhook

DELETE/v3/webhooks/{id}

Permanently removes a webhook endpoint. No further events will be delivered.

BASH
curl -X DELETE \
  https://api.runconvert.com/v3/webhooks/wh_01hx4k9m2p \
  -H "Authorization: Bearer rc_live_..."

# 204 No Content on success
Reference

Errors

All error responses include a JSON body with a machine-readable code and a human-readable message.

HTTP status codes

200OKRequest succeeded
201CreatedResource created
204No ContentSuccessful deletion
400Bad RequestInvalid body, missing required field, or unsupported format pair
401UnauthorizedMissing or invalid API key / sign-in required
403ForbiddenResource belongs to another account
404Not FoundResource does not exist
422UnprocessableInsufficient credits, no workers available
429Too Many RequestsDaily credit limit or active job limit exceeded
500Server ErrorRetry with exponential backoff

Application error codes

UNAUTHORIZEDMissing or invalid API key
SIGN_IN_REQUIREDThis operation requires a signed-in account
VALIDATION_ERRORInvalid body or missing required field (e.g. input_format)
INVALID_OPERATIONUnknown operation or unsupported input→output pair
JOB_NOT_FOUNDJob ID does not exist
JOB_FORBIDDENJob belongs to another account
TASK_NOT_FOUNDTask ID does not exist
TASK_NOT_RETRYABLEOnly error tasks can be retried
BILLING_INSUFFICIENT_CREDITSAccount has no remaining credits
NO_WORKERS_AVAILABLENo conversion workers available right now
GUEST_DAILY_LIMIT_REACHEDGuest daily limit reached (10/day) - sign up for more
FREE_TIER_DAILY_LIMIT_REACHEDFree account daily limit reached - upgrade for unlimited
ACTIVE_JOB_LIMIT_REACHEDToo many active jobs - wait for existing ones to finish
DEVICE_BLOCKEDThis device has been blocked
error-examples.json
// 400 - missing input_format, or a pair that isn't supported
{
  "success": false,
  "error": {
    "code": "INVALID_OPERATION",
    "message": "unknown operation: \"convert\""
  }
}

// 400 - malformed task graph
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Circular dependency detected in task inputs."
  }
}

// 422 - insufficient credits
{
  "success": false,
  "error": {
    "code": "BILLING_INSUFFICIENT_CREDITS",
    "message": "Insufficient credits."
  }
}
Reference

Conversion errors

When a conversion fails, its task has status error and three fields that say why: code is the broad category (below), reason is the exact cause, and message explains it in plain English with what to do next. reason_params holds the values in the message (for example the app a protected file came from). The same fields are sent in webhooks.

Check reason in your code: its values never change once published, while messages may be reworded. Older tasks and some rare failures have no reason; treat a missing or unknown value like SYSTEM_UNKNOWN.

Categories (code)

INVALID_DATAThe file itself can't be converted (protected, empty, no sound). Retrying won't help.
PROCESSING_ERRORThe converter couldn't process the file. Other engines are tried automatically first.
UNSUPPORTED_OPERATIONThis format pair can't be converted.
TIMEOUTThe conversion took longer than its time limit.
STORAGE_ERRORThe result couldn't be saved.
DEPENDENCY_ERRORThe input couldn't be fetched, or an earlier task failed.

Reasons

retry says whether converting the same file again can help.

INPUT_EMPTYINVALID_DATA
The file is emptyThis file is empty (0 bytes), so there's nothing to convert. Check the file on your device and upload it again.
INPUT_WRONG_FORMATPROCESSING_ERROR
The file's content doesn't match its nameThis file is named .{claimed}, but its content is {real}. It was probably renamed. Convert it as {real} instead.
INPUT_WEB_PAGEPROCESSING_ERROR
This is a web page, not the fileThis file is a web page (HTML), not {claimed}. If it came from a link, the link opened a page instead of the file itself. Download the file and upload it here.
INPUT_DAMAGEDPROCESSING_ERROR
The file is damagedThe file couldn't be read. It may be damaged, or renamed from a different format. Open it on your device to check, save or export a new copy, then convert that.
INPUT_INCOMPLETEPROCESSING_ERROR
The file is incompletePart of this file is missing. This happens when a download, upload or recording stopped before it finished. Get or export the file again, then convert the new copy.
INPUT_PASSWORDINVALID_DATA
The file is password-protectedThis file is locked with a password, so it can't be opened. Open it on your device, save a copy without the password, then convert that copy.
INPUT_DRM_MUSICINVALID_DATA
Copy-protected music downloadThis file is an encrypted download from {service}. Its audio is locked to that app and can't be converted. Download or export an unprotected copy of the song and convert that instead.
INPUT_DRM_VIDEOINVALID_DATA
Copy-protected videoThis file is protected by DRM (for example an iTunes Store purchase or rental, or a protected streaming download), so its video and audio are encrypted and can't be converted. Only files without DRM, such as your own recordings, exports or downloads, can be converted.
INPUT_DRM_EBOOKINVALID_DATA
Copy-protected e-bookThis e-book is protected by DRM (for example a Kindle, Kobo or Adobe Digital Editions purchase), so its content is encrypted and can't be converted. Only e-books without DRM can be converted.
INPUT_TOO_LARGEPROCESSING_ERROR
The file is too largeThis file is too large to convert. Try a smaller file, or split it into parts and convert each part.
INPUT_DOWNLOAD_FAILEDDEPENDENCY_ERROR
We couldn't get your fileThe uploaded file was no longer available when the conversion started. Upload it again and convert it.
INPUT_URL_FAILEDDEPENDENCY_ERRORretry
We couldn't download that linkThe file at this link couldn't be downloaded. Check that the link opens the file itself (not a page about it) and doesn't need a sign-in, then try again.
INPUT_UPLOAD_TIMEOUTDEPENDENCY_ERROR
The upload didn't finish in timeThe file didn't finish uploading in time, usually because the connection was slow or interrupted. Add the file again and convert it.
INPUT_NOT_UPLOADEDDEPENDENCY_ERROR
The file wasn't uploadedThe file was removed, or its upload didn't finish, before the conversion started. Add the file again and convert it.
MEDIA_NO_AUDIOINVALID_DATA
The video has no soundThis video has no audio track, so there's no audio to convert. Check that the video plays with sound, then convert that copy.
MEDIA_NO_STREAMINVALID_DATA
Nothing to convertThe file has no video or audio that this format can hold, so there was nothing to convert. Choose a different output format.
MEDIA_CODEC_UNSUPPORTEDPROCESSING_ERROR
Unsupported audio or video formatThis file's audio or video is encoded as "{codec}", which we can't read. Export the file again with a common format (for example H.264 video and AAC audio) and convert that.
MEDIA_SPATIAL_AUDIOINVALID_DATA
Spatial audio can't be convertedThis is a spatial-audio download (AVS3 Audio Vivid, for example NetEase Cloud Music 沉浸声), which can't be decoded. Download the track in standard or lossless quality (AAC or FLAC) and convert that file instead.
MEDIA_STALLEDPROCESSING_ERRORretry
The conversion stopped respondingThe conversion stopped making progress, so it was stopped. This is usually caused by a damaged part of the file. Try again; if it fails again, export a new copy of the file and convert that.
DOC_OPEN_FAILEDPROCESSING_ERROR
The document couldn't be openedThe document couldn't be opened. It may be damaged, password-protected, or saved in a format we can't read. Open it on your device, save a new copy (for example as .docx, .xlsx or .pptx), then convert that.
DOC_PDF_NO_PAGESPROCESSING_ERROR
No pages could be read from this PDFThe PDF is damaged or isn't really a PDF: no pages could be read from it. Open it in a PDF viewer to check, download it again or save it as PDF again, then convert the new copy.
DOC_NO_TEXTINVALID_DATA
No text foundNo text was found in this file, not even with text recognition (OCR). Check that it contains text: a blank page, a photo without writing or a very blurry scan has none. For a scan, a sharper copy at 300 DPI usually works.
EBOOK_DAMAGEDPROCESSING_ERROR
The e-book is damagedThe e-book's structure is broken (its EPUB package file is missing or invalid), even after we tried to repair it. Export or download it again, then convert the new copy.
MD_TOO_LARGEINVALID_DATA
The Markdown file is too largeThis Markdown file is {size} MB; the limit is {limit} MB of text. Split it into smaller files and convert each one.
IMAGE_RAW_UNKNOWNINVALID_DATA
Not a camera RAW photoThis .raw file isn't a camera RAW photo or an image format we can read. If it came from a camera, export it as DNG, TIFF or JPEG from the camera's software and convert that.
IMAGE_TOO_LARGEPROCESSING_ERROR
The image is too largeThis image has too many pixels to convert. Resize it to a smaller width and height, then convert it again.
DRAWING_EMPTYPROCESSING_ERROR
The drawing came out emptyNothing visible could be drawn from this file. It may be empty, or use features we can't read. Open it in its editor, check that it shows content, save a new copy and convert that.
DRAWING_TOO_COMPLEXPROCESSING_ERROR
The drawing is too complexThis drawing is too complex to convert in time. Remove unused layers or blocks, or export only the part you need, then convert that.
FONT_NO_SHAPESINVALID_DATA
The SVG has no shapes for a fontThe SVG has no vector shapes to turn into a font character (it may only contain an embedded picture). Export it from your editor with its shapes as paths, then convert that.
ARCHIVE_PASSWORDINVALID_DATA
The archive is password-protectedThis archive is locked with a password, so its files can't be read. Extract it on your device with the password, then convert the files or a new archive without a password.
ARCHIVE_EMPTYINVALID_DATA
The archive is emptyNo files were found inside this archive. Check it on your device, then convert an archive that contains files.
ARCHIVE_DAMAGEDPROCESSING_ERROR
The archive is damagedThis archive couldn't be opened. It may be damaged, incomplete (a download that didn't finish) or split into parts. Download or create it again, then convert the new copy.
ARCHIVE_UNSUPPORTEDPROCESSING_ERROR
The archive uses an unsupported compression methodThis archive was packed with a compression method we can't open (usually an old or uncommon one). Extract it on your device, pack the files again as a normal ZIP, then convert that.
PAIR_UNSUPPORTEDUNSUPPORTED_OPERATION
This conversion isn't supportedWe can't convert this file to the chosen format. Choose a different output format.
SYSTEM_TIMEOUTTIMEOUTretry
The conversion took too longThe conversion took longer than the time limit and was stopped. Try again; for very large files, try a smaller file or split it into parts.
SYSTEM_NO_OUTPUTPROCESSING_ERRORretry
The conversion produced no fileThe conversion finished but produced no file. Try again; if it fails again, the file may be empty or damaged.
SYSTEM_UPLOAD_FAILEDSTORAGE_ERRORretry
We couldn't save the resultYour file was converted, but the result couldn't be saved. Please convert it again.
OUTPUT_TOO_LARGESTORAGE_ERROR
The converted file is too largeThe file was converted, but the result is too large to save. Try a smaller file, lower quality or resolution settings, or split the file into parts.
SYSTEM_ENGINE_UNAVAILABLEPROCESSING_ERRORretry
The converter is busyThe converter for this file type is busy or temporarily unavailable. Please try again in a few minutes.
SYSTEM_UPSTREAM_FAILEDDEPENDENCY_ERROR
An earlier step failedThis step needs the result of an earlier step, which failed. See the earlier step for the reason.
SYSTEM_CANCELLEDDEPENDENCY_ERROR
The conversion was cancelledThis conversion was cancelled before it finished. Convert the file again if you still need it.
SYSTEM_UNKNOWNPROCESSING_ERRORretry
The file couldn't be convertedSomething went wrong while converting this file. It may be damaged, or use a feature this format doesn't support. Try again, or convert a different copy of the file.
failed-task.json
{
  "id": "task_9xkq2v",
  "name": "convert-1",
  "operation": "convert",
  "status": "error",
  "code": "INVALID_DATA",
  "reason": "INPUT_DRM_MUSIC",
  "reason_params": { "service": "QQ Music" },
  "message": "This file is an encrypted download from QQ Music. Its audio is locked to that app and can't be converted. Download or export an unprotected copy of the song and convert that instead."
}
Reference

Rate Limits

RunConvert uses a credit-based daily limit system. Each conversion costs a number of credits (visible via GET /v3/operations?input=X&output=Y). API key jobs additionally deduct from your team credit balance.

Daily credit limits

TierCredits / dayNotes
Guest (no account)10Device-based; sign up for more
Free account20Upgrade for unlimited
API key (subscribed)UnlimitedGoverned by team credit balance

Active job limit

There is a per-account limit on concurrent active jobs to keep the queue healthy. Wait for existing jobs to reach finished or error before creating new ones if you hit this limit.

limit-errors.json
// 429 - guest daily limit
{
  "success": false,
  "error": {
    "code": "GUEST_DAILY_LIMIT_REACHED",
    "message": "Daily limit reached. Sign up for a free account to get more."
  }
}

// 429 - free account limit
{
  "success": false,
  "error": {
    "code": "FREE_TIER_DAILY_LIMIT_REACHED",
    "message": "Daily limit reached. Upgrade for unlimited conversions."
  }
}

// 429 - too many concurrent jobs
{
  "success": false,
  "error": {
    "code": "ACTIVE_JOB_LIMIT_REACHED",
    "message": "Too many active jobs. Wait for existing jobs to finish before creating new ones."
  }
}
Tools

Command-line tool

runconvert converts files, folders, glob patterns and URLs from the terminal, scripts and CI with your API key. One program, no dependencies, for macOS, Windows and Linux (Intel and ARM).

Install

With Node.js: npm i -g @runconvert/cli, or run it without installing: npx @runconvert/cli ….

Sign in

runconvert login saves your key in the system keychain. In CI, set RUNCONVERT_API_KEY instead.

Where results go

ParamTypeDescription
<inputs…>reqpathsFiles, folders (add -r for subfolders), glob patterns or http(s) URLs.
--to, -treqformatOutput format, e.g. png, mp3, pdf.
--outfolderSave all results here. Default: next to each input.
-opatternOutput path pattern with {dir}, {name}, {ext} and {from}, e.g. "./mp3/{name}.{ext}".
--keep-structureflagRecreate subfolders under --out.
--optname=valueConversion setting, repeatable. List them with runconvert formats <from> <to>.
--jsonflagMachine-readable results for scripts.

runconvert help paths, help options and help env explain each part in the terminal.

terminal
runconvert login                                   # paste your rc_live_ key

runconvert convert photo.heic --to jpg             # → photo.jpg next to it
runconvert convert ./images/*.webp --to png --out ./png
runconvert convert "./Holiday Photos" --to jpg -r --keep-structure --out ./converted
runconvert convert talk.mp4 --to mp3 --opt audioBitrate=192k
runconvert convert https://example.com/report.docx --to pdf

runconvert formats mp4          # what mp4 converts to, and the credits
runconvert formats heic jpg     # the options for one conversion
runconvert jobs list
Tools

MCP server for AI apps

RunConvert works as an MCP server, so Claude, ChatGPT, Cursor, VS Code and other AI apps can convert files for you. It has three tools: list_formats, convert and get_job. Conversions use your account's credits.

Local: files on your computer

For Claude Desktop, Claude Code, Cursor and VS Code. It reads and saves files on your computer, with your API key.

Remote: mcp.runconvert.com

Add https://mcp.runconvert.com/mcp as a connector in Claude or ChatGPT and sign in with your RunConvert account. It converts files from links and returns download links. The app gets an API key named after it, which you can revoke in Dashboard → API keys.

Claude Code
claude mcp add runconvert -e RUNCONVERT_API_KEY=rc_live_... -- npx -y @runconvert/cli mcp
claude_desktop_config.json / .cursor/mcp.json
{
  "mcpServers": {
    "runconvert": {
      "command": "npx",
      "args": ["-y", "@runconvert/cli", "mcp"],
      "env": { "RUNCONVERT_API_KEY": "rc_live_..." }
    }
  }
}
Reference

SDKs & Libraries

Official, open-source (MIT) SDKs for nine languages. Each one converts a file in one call, and covers jobs, uploads, downloads, webhooks and the format list. All SDKs.

From the terminal and AI apps, use the CLI and MCP server. Any other language works with the REST API above and any HTTP client.

Community libraries

Community-maintained libraries will be listed here. Building one? Let us know.

Get your API key

Create one in Dashboard → API Keys. API conversions use credits.

Open Dashboard
// npm install @runconvert/sdk

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

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

const { saved } = await rc.convert("report.docx", { to: "pdf", outDir: "out" });

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

Add to Preferred Sources