RunConvert API v2

Welcome to RunConvert API v2! On this documentation you will find how to send API requests to convert, merge, or optimize your files using RunConvert.

Docs Contact

Welcome

Welcome to RunConvert API v2! On this documentation you will find how to send API requests to convert, merge, or optimize your files using RunConvert.

Our API uses API keys to authenticate requests. You can view and manage your API keys in the User Dashboard.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests to protected routes without authentication will also fail.

Authentication

HTTP Authentication, scheme: bearer

Every request to a protected route in RunConvert API must include an API Key so that we can identify you. Once you have signed up for an account, you can generate an API key by visiting the API keys page from your User Dashboard.

API requests are authenticated using the `Authorization: Bearer API_KEY` in the header.

Bash

curl -X GET https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer {access-token}'

Getting Started

RunConvert is an online tool to convert audio, video, image, or document files.

This guide leads you through a typical implementation of the RunConvert API. It involves creating a job with tasks to import, process, and export files.

Terminology

Understanding key concepts used in RunConvert API.

Tasks

Tasks are individual activities you can perform in RunConvert, such as importing a file, converting it, or exporting the result.

Jobs

Job is a collection of tasks. A job can have import tasks, processing tasks and export tasks defining a workflow that RunConvert should follow. For example, a job might consist of an 'import/url' task, followed by a 'convert' task, and finally an 'export/s3' task.

Import Files

Methods to import files into RunConvert. These are defined as tasks within a Job.

Import URLPOST

Import a file from a public URL.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "import-1": {
              "operation": "import/url",
              "url": "https://example.com/file.jpg",
              "filename": "file.jpg"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "import-1": {
      "operation": "import/url",
      "url": "https://example.com/file.jpg",
      "filename": "file.jpg"
    }
  }
}

Import UploadPOST

Get a signed URL to upload a file directly.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "import-1": {
              "operation": "import/upload",
              "filename": "file.jpg",
              "file_size": 102400
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "import-1": {
      "operation": "import/upload",
      "filename": "file.jpg",
      "file_size": 102400
    }
  }
}

Response Body

json

{
  "tasks": [
    {
      "operation": "import/upload",
      "result": {
        "form": {
          "url": "https://upload.runconvert.com/...",
          "parameters": {
            "signature": "..."
          }
        }
      }
    }
  ]
}

Import S3POST

Import a file from an AWS S3 bucket.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "import-1": {
              "operation": "import/s3",
              "bucket": "my-bucket",
              "region": "us-east-1",
              "access_key_id": "...",
              "secret_access_key": "...",
              "key": "files/input.jpg"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "import-1": {
      "operation": "import/s3",
      "bucket": "my-bucket",
      "region": "us-east-1",
      "access_key_id": "...",
      "secret_access_key": "...",
      "key": "files/input.jpg"
    }
  }
}

Import Google Cloud StoragePOST

Import a file from Google Cloud Storage.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "import-1": {
              "operation": "import/google-cloud-storage",
              "bucket": "my-bucket",
              "project_id": "my-project",
              "client_email": "...",
              "private_key": "...",
              "file": "input.jpg"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "import-1": {
      "operation": "import/google-cloud-storage",
      "bucket": "my-bucket",
      "project_id": "my-project",
      "client_email": "...",
      "private_key": "...",
      "file": "input.jpg"
    }
  }
}

Import Azure BlobPOST

Import a file from Azure Blob Storage.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "import-1": {
              "operation": "import/azure/blob",
              "storage_account": "myaccount",
              "container": "mycontainer",
              "storage_access_key": "...",
              "blob": "input.jpg"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "import-1": {
      "operation": "import/azure/blob",
      "storage_account": "myaccount",
      "container": "mycontainer",
      "storage_access_key": "...",
      "blob": "input.jpg"
    }
  }
}

Import SFTPPOST

Import a file from an SFTP server.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "import-1": {
              "operation": "import/sftp",
              "host": "sftp.example.com",
              "port": 22,
              "username": "user",
              "password": "password",
              "file_string": "/path/to/file.jpg"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "import-1": {
      "operation": "import/sftp",
      "host": "sftp.example.com",
      "port": 22,
      "username": "user",
      "password": "password",
      "file_string": "/path/to/file.jpg"
    }
  }
}

Import Base64POST

Import a file from a Base64 string (max 1.5MB).

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "import-1": {
              "operation": "import/base64",
              "file": "data:image/jpeg;base64,/9j/4AAQSk...",
              "filename": "image.jpg"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "import-1": {
      "operation": "import/base64",
      "file": "data:image/jpeg;base64,/9j/4AAQSk...",
      "filename": "image.jpg"
    }
  }
}

Processing Tasks

Perform file transformations.

ConvertPOST

Convert a file from one format to another.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "convert-1": {
              "operation": "convert",
              "input": "import-1",
              "input_format": "jpg",
              "output_format": "png",
              "options": {
                "quality": 80
              }
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "convert-1": {
      "operation": "convert",
      "input": "import-1",
      "input_format": "jpg",
      "output_format": "png",
      "options": {
        "quality": 80
      }
    }
  }
}

CompressPOST

Reduce the file size.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "compress-1": {
              "operation": "compress",
              "input": "import-1",
              "engine": "ilovepdf"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "compress-1": {
      "operation": "compress",
      "input": "import-1",
      "engine": "ilovepdf"
    }
  }
}

MergePOST

Merge multiple files.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "merge-1": {
              "operation": "merge",
              "input": ["import-1", "import-2"],
              "output_format": "pdf"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "merge-1": {
      "operation": "merge",
      "input": [
        "import-1",
        "import-2"
      ],
      "output_format": "pdf"
    }
  }
}

ArchivePOST

Create ZIP/TAR archives.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "archive-1": {
              "operation": "archive",
              "input": ["import-1", "convert-1"],
              "output_format": "zip"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "archive-1": {
      "operation": "archive",
      "input": [
        "import-1",
        "convert-1"
      ],
      "output_format": "zip"
    }
  }
}

Capture WebsitePOST

Capture a screenshot or PDF of a website.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "capture-1": {
              "operation": "capture_website",
              "url": "https://google.com",
              "output_format": "png"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "capture-1": {
      "operation": "capture_website",
      "url": "https://google.com",
      "output_format": "png"
    }
  }
}

OCRPOST

Extract text from images/PDFs.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "ocr-1": {
              "operation": "ocr",
              "input": "import-1",
              "language": "eng"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "ocr-1": {
      "operation": "ocr",
      "input": "import-1",
      "language": "eng"
    }
  }
}

WatermarkPOST

Add watermark to files.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "watermark-1": {
              "operation": "watermark",
              "input": "import-1",
              "text": "Confidential"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "watermark-1": {
      "operation": "watermark",
      "input": "import-1",
      "text": "Confidential"
    }
  }
}

ThumbnailPOST

Create thumbnails for videos or images.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "thumb-1": {
              "operation": "thumbnail",
              "input": "import-1",
              "output_format": "jpg"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "thumb-1": {
      "operation": "thumbnail",
      "input": "import-1",
      "output_format": "jpg"
    }
  }
}

Export Files

Export processed files.

Export URLPOST

Get a public download link.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "export-1": {
              "operation": "export/url",
              "input": "convert-1"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "export-1": {
      "operation": "export/url",
      "input": "convert-1"
    }
  }
}

Export S3POST

Export to S3.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "export-1": {
              "operation": "export/s3",
              "input": "convert-1",
              "bucket": "my-output-bucket",
              "region": "us-east-1",
              "access_key_id": "...",
              "secret_access_key": "...",
              "key": "results/output.png"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "export-1": {
      "operation": "export/s3",
      "input": "convert-1",
      "bucket": "my-output-bucket",
      "region": "us-east-1",
      "access_key_id": "...",
      "secret_access_key": "...",
      "key": "results/output.png"
    }
  }
}

Export Google Cloud StoragePOST

Export to Google Cloud Storage.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "export-1": {
              "operation": "export/google-cloud-storage",
              "input": "convert-1",
              "bucket": "my-bucket",
              "project_id": "my-project",
              "client_email": "...",
              "private_key": "...",
              "file": "output.png"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "export-1": {
      "operation": "export/google-cloud-storage",
      "input": "convert-1",
      "bucket": "my-bucket",
      "project_id": "my-project",
      "client_email": "...",
      "private_key": "...",
      "file": "output.png"
    }
  }
}

Export Azure BlobPOST

Export to Azure Blob Storage.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tasks": {
          "export-1": {
              "operation": "export/azure/blob",
              "input": "convert-1",
              "storage_account": "...",
              "container": "...",
              "storage_access_key": "...",
              "blob": "output.png"
          }
      }
  }'

Request Body

json

{
  "tasks": {
    "export-1": {
      "operation": "export/azure/blob",
      "input": "convert-1",
      "storage_account": "...",
      "container": "...",
      "storage_access_key": "...",
      "blob": "output.png"
    }
  }
}

Export SFTPPOST

Export to SFTP server.

POSThttps://api.runconvert.com/v2/process/jobs

Request Body

json

{
  "tasks": {
    "export-1": {
      "operation": "export/sftp",
      "input": "convert-1",
      "host": "...",
      "port": 22,
      "username": "...",
      "password": "...",
      "file_string": "output.png"
    }
  },
  "code_samples": [
    {
      "language": "Bash",
      "code": "curl -X POST https://api.runconvert.com/v2/process/jobs \\\n  -H 'Authorization: Bearer YOUR_API_KEY' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n      \"tasks\": {\n          \"export-1\": {\n              \"operation\": \"export/sftp\",\n              \"input\": \"convert-1\",\n              \"host\": \"...\",\n              \"port\": 22,\n              \"username\": \"...\",\n              \"password\": \"...\",\n              \"file_string\": \"output.png\"\n          }\n      }\n  }'"
    }
  ]
}

Jobs

Manage conversion jobs.

List JobsGET

Get a list of all jobs for the current user.

GEThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X GET https://api.runconvert.com/v2/process/jobs?status=completed \
  -H 'Authorization: Bearer YOUR_API_KEY'

Query Parameters

Name	Type	Description
status	string	Filter by status: created, processing, completed, failed
limit	integer	Pagination limit
offset	integer	Pagination offset

Response Body

json

{
  "data": [
    {
      "id": "job_id...",
      "status": "completed",
      "tasks": []
    }
  ],
  "meta": {
    "count": 10
  }
}

Create JobPOST

Create a new job with tasks.

POSThttps://api.runconvert.com/v2/process/jobs

Bash

curl -X POST https://api.runconvert.com/v2/process/jobs \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "tag": "my-job",
      "tasks": {
        "import-1": { "operation": "import/url", "url": "https://example.com/file.pdf" },
        "convert-1": { "operation": "convert", "input": "import-1", "output_format": "jpg" },
        "export-1": { "operation": "export/url", "input": "convert-1" }
      }
  }'

Request Body

json

{
  "tag": "my-job",
  "tasks": {
    "import-1": {
      "operation": "import/url",
      "url": "..."
    },
    "convert-1": {
      "operation": "convert",
      "input": "import-1",
      "output_format": "pdf"
    },
    "export-1": {
      "operation": "export/url",
      "input": "convert-1"
    }
  }
}

Response Body

json

{
  "id": "job_id...",
  "status": "created"
}

Show JobGET

Get details of a specific job.

GEThttps://api.runconvert.com/v2/process/jobs/{id}

Bash

curl -X GET https://api.runconvert.com/v2/process/jobs/{id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	-

Tasks

Manage individual tasks.

List TasksGET

List all tasks.

GEThttps://api.runconvert.com/v2/process/tasks

Bash

curl -X GET https://api.runconvert.com/v2/process/tasks?job_id={job_id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

Query Parameters

Name	Type	Description
job_id	string	Filter by Job ID
status	string	Filter by status

Show TaskGET

Get details of a specific task.

GEThttps://api.runconvert.com/v2/process/tasks/{id}

Bash

curl -X GET https://api.runconvert.com/v2/process/tasks/{id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

File Formats

Discover supported formats and conversions.

List All FormatsGET

Fetch all supported file formats by RunConvert.

GEThttps://api.runconvert.com/v2/core/formats

Bash

curl -X GET https://api.runconvert.com/v2/core/formats

List OutputsGET

Get supported output formats.

GEThttps://api.runconvert.com/v2/core/outputs

Bash

curl -X GET https://api.runconvert.com/v2/core/outputs?input_format=pdf

Advanced Options

Query available options for specific conversions.

Check OptionsGET

Get available engines and options for a specific input and output format.

GEThttps://api.runconvert.com/v2/core/operations

Bash

curl -X GET 'https://api.runconvert.com/v2/core/operations?input_format=jpg&output_format=png'

Query Parameters

Name	Type	Description
input_format	string	Input file extension (e.g., jpg)
output_format	string	Output file extension (e.g., png)

Webhooks

Subscribe to job and task events.

Webhooks let you receive status updates for your jobs and tasks. You can manage them via the API.

Events

job.created
job.finished
job.failed
task.created
task.finished
task.failed

List WebhooksGET

List all configured webhooks.

GEThttps://api.runconvert.com/v2/webhooks

Bash

curl -X GET https://api.runconvert.com/v2/webhooks \
  -H 'Authorization: Bearer YOUR_API_KEY'

Create WebhookPOST

Create a new webhook.

POSThttps://api.runconvert.com/v2/webhooks

Bash

curl -X POST https://api.runconvert.com/v2/webhooks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "endpoint_url": "https://mysite.com/callback",
      "events": ["job.finished"]
  }'

Request Body

json

{
  "endpoint_url": "https://mysite.com/callback",
  "events": [
    "job.finished"
  ]
}

Delete WebhookDELETE

Delete a webhook.

DELETEhttps://api.runconvert.com/v2/webhooks/{id}

Bash

curl -X DELETE https://api.runconvert.com/v2/webhooks/{id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

Errors

Possible error codes and meanings.

HTTP Status Codes

Code	Meaning
400	Bad Request
401	Unauthorized
402	Payment Required (Insufficient Credits)
403	Forbidden
404	Not Found
429	Too Many Requests
500	Internal Server Error

Application Codes

Code	Meaning
upload_timeout	File upload timeout exceeded.
insufficient_credits	Available conversion minutes/credits are finished.
processing_failed	Task failed due to internal process failure.

Rate Limits

RunConvert API is rate limited. If your API requests are rate limited, you will receive a 429 HTTP response code.