API Reference
Convert any file programmatically. Import files, apply conversions, and export results - all in a single API call.
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
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.
# 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"
}
}
}'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.
curl https://api.runconvert.com/v3/jobs \
-H "Authorization: Bearer rc_live_..." \
-H "Content-Type: application/json"{
"success": false,
"error": {
"code": "AUTH_INVALID_TOKEN",
"message": "Invalid or expired token."
}
}Quickstart
Convert an MP4 video to MP3 audio from a public URL in four steps.
Import
Define an import/url task pointing at your source file.
Convert
Add a convert task. Both input_format and output_format are required.
Export
Add an export/url task to get a download link for the output.
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.
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"
}
}
}'// 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"
}]
}
}
]
}}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
Create a job
| Param | Type | Description |
|---|---|---|
| tasksreq | object | Named task definitions. Keys are task names referenced by downstream tasks via input. Names must be alphanumeric with hyphens or underscores (max 64 chars). |
| tag | string | Optional label for filtering in the list endpoint. |
| metadata | object | Arbitrary key-value data stored with the job. |
List jobs
| Param | Type | Description |
|---|---|---|
| filter[status] | string | Filter by status: waiting | processing | finished | error |
| filter[tag] | string | Filter by tag. |
| include | string | Pass "tasks" to embed task objects in each job. |
| page | integer | Page number. Default: 1. |
| per_page | integer | Results per page. Default: 100. |
Get a job
| Param | Type | Description |
|---|---|---|
| include | string | Pass "tasks" to include task objects in the response. |
Cancel a job
Cancels all pending tasks. Credits for the tasks that didn't finish are refunded.
Delete a job
# 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_..."{
"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"
}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
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
| Param | Type | Description |
|---|---|---|
| filter[job_id] | string | Filter by job ID. |
| filter[status] | string | Filter by status: waiting | processing | finished | error |
| filter[operation] | string | Filter by operation type. |
| include | string | Comma-separated extras: retries, payload, depends_on_tasks |
| page | integer | Page number. Default: 1. |
| per_page | integer | Results 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
Only tasks in error status can be retried.
{
"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/url
Import a file from any publicly accessible URL. RunConvert fetches the file at job execution time.
| Param | Type | Description |
|---|---|---|
| operationreq | string | Must be "import/url". |
| source_urlreq | string | Publicly accessible http(s) URL of the file to import. The file keeps the name from the URL (or the server's Content-Disposition). |
{
"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/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.
| Param | Type | Description |
|---|---|---|
| operationreq | string | Must 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.
{
"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" }
}
}// 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"
}]
}
}# 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 receivedconvert
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.
| Param | Type | Description |
|---|---|---|
| operationreq | string | Must be "convert". |
| inputreq | string | Name of the import task whose output to convert. |
| input_formatreq | string | Source format extension, e.g. mp4, png, docx. |
| output_formatreq | string | Target format extension, e.g. mp3, webp, pdf. |
| preferred_engine | string | Request a specific engine when multiple are available for this pair. Falls back to the default if not found. |
| <option name> | any | Engine 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_error | boolean | If true, the job continues even if this task fails. |
curl -X POST https://api.runconvert.com/v3/jobs \
-H "Authorization: Bearer $RUNCONVERT_API_KEY" \
-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",
"audioBitrate": "192k"
},
"export-1": {
"operation": "export/url",
"input": "convert-1"
}
}
}'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);package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
)
func main() {
body, _ := json.Marshal(map[string]any{
"tasks": map[string]any{
"import-1": map[string]any{
"operation": "import/url",
"source_url": "https://example.com/video.mp4",
},
"convert-1": map[string]any{
"operation": "convert",
"input": "import-1",
"input_format": "mp4",
"output_format": "mp3",
"audioBitrate": "192k",
},
"export-1": map[string]any{
"operation": "export/url",
"input": "convert-1",
},
},
})
req, _ := http.NewRequest("POST", "https://api.runconvert.com/v3/jobs", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("RUNCONVERT_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
fmt.Println(resp.Status)
}import os, requests
resp = requests.post(
"https://api.runconvert.com/v3/jobs",
headers={"Authorization": f"Bearer {os.environ['RUNCONVERT_API_KEY']}"},
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",
"audioBitrate": "192k",
},
"export-1": {
"operation": "export/url",
"input": "convert-1",
},
}
},
)
print(resp.json()["id"])require "net/http"
require "json"
uri = URI("https://api.runconvert.com/v3/jobs")
req = Net::HTTP::Post.new(uri,
"Content-Type" => "application/json",
"Authorization" => "Bearer #{ENV['RUNCONVERT_API_KEY']}"
)
req.body = {
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" },
}
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts JSON.parse(res.body)["id"]use reqwest::Client;
use serde_json::json;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let job: serde_json::Value = Client::new()
.post("https://api.runconvert.com/v3/jobs")
.bearer_auth(std::env::var("RUNCONVERT_API_KEY")?)
.json(&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",
"audioBitrate": "192k"
},
"export-1": {
"operation": "export/url",
"input": "convert-1"
}
}
}))
.send().await?.json().await?;
println!("{}", job["id"]);
Ok(())
}using System.Net.Http.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add(
"Authorization",
$"Bearer {Environment.GetEnvironmentVariable("RUNCONVERT_API_KEY")}");
var response = await client.PostAsJsonAsync("https://api.runconvert.com/v3/jobs", new {
tasks = new Dictionary<string, object> {
["import-1"] = new { operation = "import/url", source_url = "https://example.com/video.mp4" },
["convert-1"] = new {
operation = "convert", input = "import-1",
input_format = "mp4", output_format = "mp3",
audioBitrate = "192k"
},
["export-1"] = new { operation = "export/url", input = "convert-1" },
}
});
Console.WriteLine(await response.Content.ReadAsStringAsync());<?php
$ch = curl_init("https://api.runconvert.com/v3/jobs");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("RUNCONVERT_API_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"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"],
],
]),
]);
echo json_decode(curl_exec($ch))->id;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.
| Param | Type | Description |
|---|---|---|
| input | string | Input format extension (e.g. mp4). Returns all valid output formats plus credit cost. |
| output | string | Combined with input - returns available engines and their options for this specific pair. |
| category | string | Filter 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.
# 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"// 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/url
Generate a temporary public download URL for the converted file.
| Param | Type | Description |
|---|---|---|
| operationreq | string | Must be "export/url". |
| inputreq | string | Name of the convert task to export. |
| archive | boolean | If true, all input files are bundled into one ZIP download. |
| archive_multiple | boolean | Bundle 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_name | string | The ZIP's file name, e.g. "report-pages" → report-pages.zip (default export.zip). |
// 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"
}]
}
}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.
| Param | Type | Description |
|---|---|---|
| constant_quality | string | Video (mp4, mov, mkv, m4v → same): H.264 CRF, higher is smaller. "28" balanced, "32" small. WebM uses VP9's scale: "42" balanced. |
| resize_video | string | Video: "1080p" | "720p" | "480p". |
| audioBitrate | string | MP3 → MP3: "64k" | "96k" | "128k". |
| image_quality | integer | JPG / WebP → same: 1-100 (72 balanced). |
| png_quality | string | PNG → PNG: "low" | "medium" | "high" or "60-80" (pngquant; transparency kept). |
| max_file_size | integer | JPG: target size in KB (e.g. 100). The photo is scaled down if quality alone can't reach it. |
| gif_lossy / gif_colors | integer | GIF → GIF: lossy strength 0-200, palette size 2-256. Animation kept. |
| pdf_compression | string | PDF → PDF: "low" (300 dpi) | "medium" (150 dpi) | "high" (72 dpi). |
// 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
}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.
| Param | Type | Description |
|---|---|---|
| split | string | PDF → PDF: "pages" (one PDF per page, up to 500) | "ranges". |
| page_ranges | string | With split "ranges": "1-3, 5, 8-" (8- runs to the last page). |
| pages | string | PDF → JPG / PNG: "all" renders every page (up to 200); without it, the first page only. |
| dpi | integer | PDF → JPG / PNG with pages all: 36-600 (default 150). |
// 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" }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.
| Param | Type | Description |
|---|---|---|
| page_size | string | Images → PDF: "fit" (default) | "a4" | "letter". |
| frame_delay | integer | Images → GIF: milliseconds per frame, 20-10000 (default 500). |
| loop | boolean | Images → GIF: false plays once (default loops). |
| width / height | integer | Any image conversion: resize to fit inside this box, proportions kept. |
| fit_mode | string | "shrink" only ever makes an image smaller. |
// 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
}Trim video and audio
Keep the part between two positions in the input. Works on any audio or video conversion, including the same format.
| Param | Type | Description |
|---|---|---|
| trim_start | string | Start position: seconds ("12.5") or "HH:MM:SS.xxx". Also trimStart. |
| trim_end | string | End position in the input (not a length). Also trimEnd. |
// 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"
}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.
// 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 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 acceptedjob.processingThe first task in the job started runningjob.finishedAll tasks completed successfullyjob.errorOne or more tasks failed (without ignore_error)task.finishedA single task completed successfullytask.errorA single task failedPayload 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.
// 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"
}
}// 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
}]
}
}
}Create Webhook
| Param | Type | Description |
|---|---|---|
| urlreq | string | HTTPS URL that will receive POST requests. |
| events | string[] | Event types to subscribe to. Default: job.finished and job.error. |
| description | string | Human-readable label for this endpoint. |
The full secret is returned once on creation only. Store it securely - subsequent reads return a masked value.
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"
}'{
"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"
}List & Get Webhooks
Returns all webhook endpoints for your account.
Returns a single endpoint. The secret is masked after creation.
Test ping
Sends a test delivery to the endpoint URL to verify it is reachable.
{
"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"
}Update Webhook
Update any combination of fields. Only provided fields are changed.
| Param | Type | Description |
|---|---|---|
| url | string | New HTTPS endpoint URL. |
| events | string[] | Replace the event subscription list. |
| description | string | Update the label. |
| enabled | boolean | Set to false to pause delivery without deleting the endpoint. |
# 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"] }'Delete Webhook
Permanently removes a webhook endpoint. No further events will be delivered.
curl -X DELETE \
https://api.runconvert.com/v3/webhooks/wh_01hx4k9m2p \
-H "Authorization: Bearer rc_live_..."
# 204 No Content on successErrors
All error responses include a JSON body with a machine-readable code and a human-readable message.
HTTP status codes
200OKRequest succeeded201CreatedResource created204No ContentSuccessful deletion400Bad RequestInvalid body, missing required field, or unsupported format pair401UnauthorizedMissing or invalid API key / sign-in required403ForbiddenResource belongs to another account404Not FoundResource does not exist422UnprocessableInsufficient credits, no workers available429Too Many RequestsDaily credit limit or active job limit exceeded500Server ErrorRetry with exponential backoffApplication error codes
UNAUTHORIZEDMissing or invalid API keySIGN_IN_REQUIREDThis operation requires a signed-in accountVALIDATION_ERRORInvalid body or missing required field (e.g. input_format)INVALID_OPERATIONUnknown operation or unsupported input→output pairJOB_NOT_FOUNDJob ID does not existJOB_FORBIDDENJob belongs to another accountTASK_NOT_FOUNDTask ID does not existTASK_NOT_RETRYABLEOnly error tasks can be retriedBILLING_INSUFFICIENT_CREDITSAccount has no remaining creditsNO_WORKERS_AVAILABLENo conversion workers available right nowGUEST_DAILY_LIMIT_REACHEDGuest daily limit reached (10/day) - sign up for moreFREE_TIER_DAILY_LIMIT_REACHEDFree account daily limit reached - upgrade for unlimitedACTIVE_JOB_LIMIT_REACHEDToo many active jobs - wait for existing ones to finishDEVICE_BLOCKEDThis device has been blocked// 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."
}
}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_DATAINPUT_WRONG_FORMATPROCESSING_ERRORINPUT_WEB_PAGEPROCESSING_ERRORINPUT_DAMAGEDPROCESSING_ERRORINPUT_INCOMPLETEPROCESSING_ERRORINPUT_PASSWORDINVALID_DATAINPUT_DRM_MUSICINVALID_DATAINPUT_DRM_VIDEOINVALID_DATAINPUT_DRM_EBOOKINVALID_DATAINPUT_TOO_LARGEPROCESSING_ERRORINPUT_DOWNLOAD_FAILEDDEPENDENCY_ERRORINPUT_URL_FAILEDDEPENDENCY_ERRORretryINPUT_UPLOAD_TIMEOUTDEPENDENCY_ERRORINPUT_NOT_UPLOADEDDEPENDENCY_ERRORMEDIA_NO_AUDIOINVALID_DATAMEDIA_NO_STREAMINVALID_DATAMEDIA_CODEC_UNSUPPORTEDPROCESSING_ERRORMEDIA_SPATIAL_AUDIOINVALID_DATAMEDIA_STALLEDPROCESSING_ERRORretryDOC_OPEN_FAILEDPROCESSING_ERRORDOC_PDF_NO_PAGESPROCESSING_ERRORDOC_NO_TEXTINVALID_DATAEBOOK_DAMAGEDPROCESSING_ERRORMD_TOO_LARGEINVALID_DATAIMAGE_RAW_UNKNOWNINVALID_DATAIMAGE_TOO_LARGEPROCESSING_ERRORDRAWING_EMPTYPROCESSING_ERRORDRAWING_TOO_COMPLEXPROCESSING_ERRORFONT_NO_SHAPESINVALID_DATAARCHIVE_PASSWORDINVALID_DATAARCHIVE_EMPTYINVALID_DATAARCHIVE_DAMAGEDPROCESSING_ERRORARCHIVE_UNSUPPORTEDPROCESSING_ERRORPAIR_UNSUPPORTEDUNSUPPORTED_OPERATIONSYSTEM_TIMEOUTTIMEOUTretrySYSTEM_NO_OUTPUTPROCESSING_ERRORretrySYSTEM_UPLOAD_FAILEDSTORAGE_ERRORretryOUTPUT_TOO_LARGESTORAGE_ERRORSYSTEM_ENGINE_UNAVAILABLEPROCESSING_ERRORretrySYSTEM_UPSTREAM_FAILEDDEPENDENCY_ERRORSYSTEM_CANCELLEDDEPENDENCY_ERRORSYSTEM_UNKNOWNPROCESSING_ERRORretry{
"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."
}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
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.
// 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."
}
}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
| Param | Type | Description |
|---|---|---|
| <inputs…>req | paths | Files, folders (add -r for subfolders), glob patterns or http(s) URLs. |
| --to, -treq | format | Output format, e.g. png, mp3, pdf. |
| --out | folder | Save all results here. Default: next to each input. |
| -o | pattern | Output path pattern with {dir}, {name}, {ext} and {from}, e.g. "./mp3/{name}.{ext}". |
| --keep-structure | flag | Recreate subfolders under --out. |
| --opt | name=value | Conversion setting, repeatable. List them with runconvert formats <from> <to>. |
| --json | flag | Machine-readable results for scripts. |
runconvert help paths, help options and help env explain each part in the 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 listMCP 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 mcp add runconvert -e RUNCONVERT_API_KEY=rc_live_... -- npx -y @runconvert/cli mcp{
"mcpServers": {
"runconvert": {
"command": "npx",
"args": ["-y", "@runconvert/cli", "mcp"],
"env": { "RUNCONVERT_API_KEY": "rc_live_..." }
}
}
}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.
Node.js
npm install @runconvert/sdkGitHub ↗Docs →Python
pip install runconvertGitHub ↗Docs →Go
go get github.com/runconvert/runconvert-goGitHub ↗Docs →Ruby
gem install runconvertGitHub ↗Docs →PHP
composer require runconvert/runconvert-phpGitHub ↗Docs →Laravel
composer require runconvert/runconvert-laravelGitHub ↗Docs →Java
implementation("com.runconvert:runconvert-java:0.1.0")GitHub ↗Docs →.NET
dotnet add package RunConvertGitHub ↗Docs →Rust
cargo add runconvertGitHub ↗Docs →
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.
// 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" });// go get github.com/runconvert/runconvert-go
rc := runconvert.New("") // reads RUNCONVERT_API_KEY
res, err := rc.Convert(ctx, "report.docx", runconvert.ConvertOptions{
To: "pdf",
OutDir: "out",
})# pip install runconvert
from runconvert import RunConvert
rc = RunConvert() # reads RUNCONVERT_API_KEY
result = rc.convert("report.docx", "pdf", out_dir="out")# gem install runconvert
require "runconvert"
rc = RunConvert::Client.new # reads RUNCONVERT_API_KEY
rc.convert("report.docx", to: "pdf", out_dir: "out")// cargo add runconvert
use runconvert::{Client, ConvertOptions};
let rc = Client::new(None); // reads RUNCONVERT_API_KEY
rc.convert("report.docx", ConvertOptions::to("pdf").out_dir("out")).await?;// dotnet add package RunConvert
using RunConvert;
using var rc = new RunConvertClient(); // reads RUNCONVERT_API_KEY
await rc.ConvertAsync("report.docx", new ConvertOptions { To = "pdf", OutDir = "out" });// composer require runconvert/runconvert-php
use RunConvert\RunConvert;
$rc = new RunConvert(); // reads RUNCONVERT_API_KEY
$result = $rc->convert('report.docx', 'pdf', ['out_dir' => 'out']);