Documentation: file conversion API, MCP and CLI

Converting a file

Open conved.com and click Choose files, or drag files onto the page. You can upload up to 10 files at once, each up to 100 MB.
Pick the target format. Only formats that all uploaded files can be converted to are offered; with many formats you can search by name or extension (e.g. word finds DOC).
Click Convert to …. When the conversion finishes, a Download button appears next to each file.

We support over 529 formats – documents, spreadsheets, presentations, images, vector graphics, audio, video, e-books, archives, fonts, CAD, GIS and more. See the list of formats for what each one can be converted to.

Converting from a link

Instead of uploading, paste a link into the field under or paste a link (or simply press Ctrl+V anywhere on the page):

A file on the web – any public http(s) address of a file; we download it and offer the target formats.
Video or music from YouTube (including Shorts), X (Twitter) and Instagram – convert it to MP4, MP3 and other formats. Some Instagram posts are not available without signing in; videos without a sound track cannot be converted to audio.

Results, ZIP and e-mail

With several files, All files in one ZIP archive downloads all results at once.
Email me the download link – useful for large files or downloading on another device. The e-mail is sent once all files are converted.
If a file cannot be converted, you will see the reason under its name (e.g. the source is damaged or the conversion took too long).
New conversion starts over and deletes the uploaded files.

Limits

What	Website (free)	Free account (API, MCP, command line)
File size	100 MB	100 MB per file
Files per conversion	10	one file per request
Conversions	10 files per hour, of which 3 online videos	10 per hour per account, of which 3 online videos

Privacy and retention

Uploaded files are used only for the conversion. They are deleted from the web server as soon as they are sent for conversion; files that are never converted are deleted within 24 hours.
Results are available for 14 days (expires_at), then deleted automatically. Download links are signed and expire with the result.
We do not read your files or use them to train AI. Deleting your account also deletes the results that are still stored.
Files are converted on our own servers in isolated containers without network access to your data; nothing is shared with third parties.

Account and API tokens

The command-line tool, the API and MCP need an account. Sign in with your email – we send you a 6-digit code; if you don't have an account yet, a free one is created (no password needed, you can set one later). Free accounts have the same limits as the website, counted per account. Need more? Contact us. In your account:

Create a token (e.g. one per server or computer). The token starts with cvd_ – keep it safe, like a password. Show and Copy next to each token display it again.
Revoke a token at any time; programs using it stop working immediately.
The account page shows your usage and limits, your recent conversions and the applications connected through MCP (disconnect them there).

Command-line tool `conved`

A single bash script for Linux and macOS – it needs only bash and curl. Version 1.0.7.

Download conved

SHA-256: 544fd7d1a096d65e56f3afca0198230dda8fc4e5d57e50a390433846bc4701ff

mkdir -p ~/bin
curl -fsSL https://www.conved.com/public/cli/conved -o ~/bin/conved
echo "544fd7d1a096d65e56f3afca0198230dda8fc4e5d57e50a390433846bc4701ff  $HOME/bin/conved" | sha256sum -c   # optional; macOS: shasum -a 256 -c
chmod +x ~/bin/conved
conved login          # paste your API token

The token is stored in ~/.config/conved/token (readable only by you). On servers you can pass it in the environment variable CONVED_TOKEN or point CONVED_TOKEN_FILE to a file.

Commands

`conved convert <file\|URL> -t <format> [-o <output>]`	Convert and download the result. Without `-o` the result is saved next to the source (`slides.ppt` → `slides.pdf`). Prints the path of the result.
`--no-wait`	Only submit the job and print its ID.
`--timeout <s>`	How long to wait for the result (default 900 s).
`-q`	Quiet – no progress messages.
`conved status <id> [--wait <s>]`	Job status: `waiting`, `done` or `error`.
`conved get <id> [-o <output>]`	Download the result of a finished job.
`conved formats [<format>]`	All supported conversions, or the targets for one format.
`conved me`	Your account, limits and usage.
`conved login` / `conved logout`	Store or remove the token.

Exit codes

Progress and errors go to stderr; stdout contains only the path of the result, so the tool is easy to use in scripts.

`0`	done
`1`	wrong usage (missing argument, file not found, unknown job)
`2`	conversion failed, or the format / conversion is not supported
`3`	limit reached
`4`	missing or invalid token
`5`	network or server error
`6`	timeout – the job is still running (check it later with `conved status`)

Examples

conved convert slides.ppt -t pdf
conved convert report.docx -t pdf -o /var/www/public/report.pdf
conved convert 'https://www.youtube.com/watch?v=3RmQTYLD398' -t mp3
conved formats heic

# convert every PowerPoint in a folder, keep going on errors
for f in *.ppt; do conved convert "$f" -t pdf -q || echo "failed: $f"; done

# cron: convert a file when it changes, alert on failure
*/5 * * * * cd /srv/slides && [ deck.pptx -nt deck.pdf ] && \
    CONVED_TOKEN_FILE=/etc/conved.token conved convert deck.pptx -t pdf -q \
    || true

REST API

Base URL https://www.conved.com/api/v1. Every request needs the header Authorization: Bearer <token>. Responses are JSON (also for errors); use HTTPS only.

A conversion is a job: you submit a file and a target format, the job runs on our conversion servers, and when it is done you get a signed download_url valid for 14 days. Short conversions finish within the request if you send wait.

`POST /convert`

Submit a file (multipart/form-data, field file) or a link (url).

`file`	the file to convert; its extension determines the source format
`url`	instead of a file: a public file URL, or a YouTube / X / Instagram link
`to`	target format, e.g. `pdf`, `docx`, `jpg`, `mp3`
`from`	optional: source format, when the file name or URL has no usable extension (e.g. `download.php?id=5`)
`wait`	optional: wait up to this many seconds (max. 40) for the result

curl -H "Authorization: Bearer $CONVED_TOKEN" \
     -F file=@slides.ppt -F to=pdf -F wait=40 \
     https://www.conved.com/api/v1/convert

Response 200 when the job finished within wait, otherwise 202 (still running):

{
  "id": "q4x7ma2kfo3c5bvhn6tyrlwe2u",
  "status": "done",
  "name": "slides.pdf",
  "from": "ppt",
  "to": "pdf",
  "size": 4529011,
  "download_url": "https://hosting2.synetix.cz/conved/d/q4x7…/slides.pdf"
}

`GET /jobs/<id>[?wait=30]`

Job status. status is waiting, done (with size, download_url and expires_at) or error (with an error code: for example timeout, killed (too demanding), tool_error, empty_output, unsupported, source_unavailable, no_audio, expired (result deleted after 14 days), not_found, internal). With wait the request waits up to that many seconds (max. 40) for the job to finish – the recommended way to poll.

`GET /jobs/<id>/download`

Redirects (303) to the result; use curl -L. Returns 409 when the job is not finished or failed.

`GET /formats[?from=ppt]`

{ "formats": { "ppt": ["epub", "jpg", "odp", "pdf", "png", "pptx", "svg", …] } }

`GET /me`

{ "email": "you@example.com", "plan": "free", "dailyLimit": 0, "hourLimit": 10,
  "maxFileMb": 100, "usedToday": 3, "usedHour": 1 }

plan is free (limit per hour, counted in the last 60 minutes) or custom (limit per 24 hours). 0 in any limit means unlimited. Every accepted conversion counts, also one that fails later.

MCP server (AI assistants)

AI assistants and agents that support the Model Context Protocol can convert files with conved.com directly. Server URL https://www.conved.com/mcp (Streamable HTTP). The first time you use it, the application opens conved.com in your browser: sign in with your email (a free account is created if you don't have one) and allow the connection. Conversions count toward the limits of your account.

Connecting

Claude (claude.ai and the Claude apps): Customize → Connectors → Add custom connector, URL https://www.conved.com/mcp (leave the OAuth fields empty), then Connect.
ChatGPT: add the URL https://www.conved.com/mcp as a developer-mode app under Settings → Apps.
Claude Code: claude mcp add --transport http conved https://www.conved.com/mcp, then /mcp → conved → Authenticate.

Instead of signing in through the browser, you can also send an API token from your account – e.g. in Claude Code:

claude mcp add --transport http conved https://www.conved.com/mcp \
    --header "Authorization: Bearer $CONVED_TOKEN"

Cursor, VS Code and other clients with a JSON configuration (or omit headers to sign in through the browser):

{
  "mcpServers": {
    "conved": {
      "url": "https://www.conved.com/mcp",
      "headers": { "Authorization": "Bearer cvd_…" }
    }
  }
}

Authentication

MCP clients sign in with OAuth 2.1 automatically: /mcp answers 401 with a link to /.well-known/oauth-protected-resource/mcp, the client registers itself (dynamic client registration) and opens /oauth/authorize in the browser. Authorization server metadata: https://www.conved.com/.well-known/oauth-authorization-server (PKCE S256, refresh tokens). Alternatively send an API token from your account in Authorization: Bearer cvd_…. The server is listed in the official MCP Registry as com.conved/mcp.

Tools

`list_formats`	target formats for one source (`from`), formats of a `category`, or the list of categories
`convert`	convert a file given by `url`, as `text` + `filename` (Markdown, HTML, CSV, SVG…, max. 1 MB) or as `data_base64` + `filename` (max. 2 MB) to the format `to`; optional `from`; waits up to `wait_seconds` (max. 25)
`create_upload`	one-time upload link (1 hour) for a file that is not online: an upload page where you pick the file in the browser (the assistant then gets the result), or a `curl` command for agents that can run commands
`get_job`	status of a job (by `id`, or by `upload_id` from `create_upload`), optionally waiting for it to finish
`list_jobs`	recent conversions of your account
`get_account`	daily limit, conversions used, maximum file size

Results come back as a download_url. With return: "content" the assistant also gets small results inline – text formats (txt, md, csv, html, json, xml, srt…) up to 100 kB and images (png, jpg, gif, webp) up to 1 MB – so it can read or show them right away, e.g. “convert this PDF to text and summarize it”.

Files on your computer: in chat apps the assistant gives you an upload page (create_upload) – choose the file there and go back to the chat; agents that can run commands (Claude Code, Cursor…) upload it themselves with curl. Download links are served by our conversion server hosting2.synetix.cz and are valid for 14 days (expires_at). Each conversion gives one file; there are no conversion options yet. Online video links are not available through MCP.

Errors

Errors have the form { "error": "<code>", "message": "<human-readable text>" }.

HTTP	`error`	Meaning
400	`bad_request`, `upload_failed`	missing file / URL / target format
401	`unauthorized`	missing, invalid or revoked token
404	`not_found`	unknown job (or a job of another account)
405	`method_not_allowed`	wrong HTTP method
409	`not_ready`	the job is not finished yet
413	`file_too_large`	the file exceeds your limit
415	`unsupported_format`	we cannot convert this source format
422	`unsupported_target`, `download_failed`	the conversion is not possible / the URL could not be downloaded
429	`limit_reached`	account limit reached (per hour on the free plan) – see `GET /me`
503	`node_unavailable`	conversion servers are busy or unavailable – retry later

Examples

Shell (curl)

API=https://www.conved.com/api/v1
AUTH="Authorization: Bearer $CONVED_TOKEN"

# submit and wait up to 40 s
curl -s -H "$AUTH" -F file=@report.docx -F to=pdf -F wait=40 $API/convert

# still running? poll, then download
curl -s -H "$AUTH" "$API/jobs/<id>?wait=30"
curl -sL -H "$AUTH" "$API/jobs/<id>/download" -o report.pdf

PHP

$ch = curl_init('https://www.conved.com/api/v1/convert');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVED_TOKEN')],
    CURLOPT_POSTFIELDS => ['file' => new CURLFile('slides.ppt'), 'to' => 'pdf', 'wait' => 40],
    CURLOPT_RETURNTRANSFER => true,
]);
$job = json_decode(curl_exec($ch), true);
while (($job['status'] ?? '') === 'waiting') {   // longer conversions
    $ch = curl_init("https://www.conved.com/api/v1/jobs/{$job['id']}?wait=30");
    curl_setopt_array($ch, [CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CONVED_TOKEN')], CURLOPT_RETURNTRANSFER => true]);
    $job = json_decode(curl_exec($ch), true);
}
if ($job['status'] === 'done') {
    copy($job['download_url'], 'slides.pdf');
} else {
    throw new RuntimeException($job['message'] ?? $job['error'] ?? 'conversion failed');
}

Python

# pip install requests
import os, requests

api = "https://www.conved.com/api/v1"
auth = {"Authorization": f"Bearer {os.environ['CONVED_TOKEN']}"}

with open("slides.ppt", "rb") as f:
    job = requests.post(f"{api}/convert", headers=auth, files={"file": f},
                        data={"to": "pdf", "wait": 40}).json()
while job.get("status") == "waiting":
    job = requests.get(f"{api}/jobs/{job['id']}", headers=auth, params={"wait": 30}).json()
if job.get("status") != "done":
    raise RuntimeError(job)
open("slides.pdf", "wb").write(requests.get(job["download_url"]).content)

Documentation

Converting a file

Converting from a link

Results, ZIP and e-mail

Limits

Privacy and retention

Account and API tokens

Command-line tool conved

Commands

Exit codes

Examples

REST API

POST /convert

GET /jobs/<id>[?wait=30]

GET /jobs/<id>/download

GET /formats[?from=ppt]

GET /me

MCP server (AI assistants)

Connecting

Authentication

Tools

Errors

Examples

Shell (curl)

PHP

Python

Command-line tool `conved`

`POST /convert`

`GET /jobs/<id>[?wait=30]`

`GET /jobs/<id>/download`

`GET /formats[?from=ppt]`

`GET /me`