API reference

A REST API for converting files programmatically. Available on Business and Enterprise plans — create a key from your dashboard. Every endpoint below is live today, not a preview.

Convert a file

POST /api/v1/convert — synchronous: the response includes a signed download URL directly, no polling required for formats that convert in well under a second (image, spreadsheet, PDF, archive). A long audio/video conversion holds the connection open for its actual duration rather than timing out early.

curl -X POST https://convyx.io/api/v1/convert \
  -H "Authorization: Bearer cvx_live_xxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "sourceFormat=png" \
  -F "targetFormat=webp" \
  -F "retention=24h"

Response:

{
  "jobId": "35562e3e-4268-49c5-8534-a702b16c0b5f",
  "status": "completed",
  "sourceFormat": "png",
  "targetFormat": "webp",
  "outputFileName": "converted.webp",
  "fileSizeBytes": 84213,
  "downloadUrl": "https://storage.convyx.io/...", // signed, expires in 15 minutes
  "expiresAt": "2026-08-02T17:17:50.316Z"
}

Look up a job

GET /api/v1/jobs/:id— every job created via the API or the dashboard shows up here and in your account's conversion history, since both write to the same table.

curl https://convyx.io/api/v1/jobs/35562e3e-4268-49c5-8534-a702b16c0b5f \
  -H "Authorization: Bearer cvx_live_xxxxxxxxxxxx"

JavaScript plain fetch

No published SDK package yet — official JS/Python/Go/PHP clients are on the roadmap. Until then, it's a plain HTTP API:

const form = new FormData();
form.set("file", fileBlob);
form.set("sourceFormat", "png");
form.set("targetFormat", "webp");

const res = await fetch("https://convyx.io/api/v1/convert", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.CONVYX_API_KEY}` },
  body: form,
});
const { downloadUrl } = await res.json();

Python

import requests

with open("photo.png", "rb") as f:
    res = requests.post(
        "https://convyx.io/api/v1/convert",
        headers={"Authorization": f"Bearer {os.environ['CONVYX_API_KEY']}"},
        files={"file": f},
        data={"sourceFormat": "png", "targetFormat": "webp"},
    )
download_url = res.json()["downloadUrl"]

Webhooks coming soon

The synchronous API above doesn't need them (you get the result in the response), but webhook delivery for a future async job-submission endpoint is planned — the underlying table already exists, delivery isn't wired up yet.

Rate limits

60 requests/minute on Business, 600 requests/minute on Enterprise, enforced per API key. The current limit and remaining quota are returned on every response via X-RateLimit-* headers.