Developer API

The same conversion pipeline that runs this site, callable from your own code. Upload a file, get a job id back, poll until it finishes, download the result. Every format pair and tool on the site works through the API, including STL to STEP, mesh repair, and the print analysis tools.

Authentication

Create an API key under Settings > API Keys & Webhooks (free account works). The full key is shown once at creation. Send it with every request:

Authorization: Bearer cf_live_...

Keys inherit your plan's limits. If a key leaks, delete it in settings and create a new one. Deletion takes effect immediately.

Submit a conversion

POST /api/v1/convert

Multipart form upload. Returns 202 Accepted with a job id.

Field	Description
`file`required	The file to convert.
`target_format`required	Output format id, e.g. `STEP`, `PDF`, `GEOJSON`. Case-insensitive.
`source_format`	Input format id. If omitted, it is inferred from the file extension.
`processor`	Explicit processor id for tools that share a format pair, e.g. `mesh_repair` for STL repair instead of plain STL passthrough.
`options`	JSON object with conversion settings, same options the site's tool pages use.
`webhook_url`	Public http(s) URL we POST to when the job finishes, so you can skip polling. See Webhooks below.

curl -X POST https://www.converterflow.io/api/v1/convert \
  -H "Authorization: Bearer cf_live_..." \
  -F "file=@bracket.stl" \
  -F "target_format=STEP"

# 202
{
  "job_id": "6f9c1e2a-...",
  "status": "waiting",
  "poll_url": "/api/v1/jobs/6f9c1e2a-..."
}

Check a job

GET /api/v1/jobs/{job_id}

Poll every few seconds until status is completed or error. Polling is cheap: it counts against the per-minute limit but never against your daily conversion quota.

curl https://www.converterflow.io/api/v1/jobs/6f9c1e2a-... \
  -H "Authorization: Bearer cf_live_..."

# 200
{
  "job_id": "6f9c1e2a-...",
  "status": "completed",
  "progress": 100,
  "download_url": "/api/v1/jobs/6f9c1e2a-.../download"
}

download_url appears only when the job completes. It is relative to https://converterflow.io and needs the same Authorization header. Fetch it promptly: converted files are deleted after download or within 24 hours.

Rate limits

Plan	Requests / minute	Conversions / day
Free	5	25
Basic	10	100
Pro	30	500
Ultimate	60	2,000

Daily counters reset at midnight UTC. Responses to conversion submissions include X-RateLimit-Limit-Day and X-RateLimit-Remaining-Day headers. File size limits follow your plan, the same as the web tools. Need more? Get in touch.

Errors

Errors come back as JSON with an error field and a standard status code:

Status	Meaning
`400`	Unsupported format pair, unknown format id, or malformed options.
`401`	Missing, invalid, or deleted API key.
`404`	Job id not found or expired.
`413`	File exceeds your plan's size limit. The message states the limit.
`429`	Rate limit or daily quota hit. Check the rate limit headers and retry later.

Webhooks

Pass webhook_url when you submit and we POST the result to it when the job reaches a terminal state. One event per job, X-ConverterFlow-Event header set to job.completed or job.failed:

# job.completed
{
  "job_id": "6f9c1e2a-...",
  "status": "completed",
  "download_url": "/api/v1/jobs/6f9c1e2a-.../download"
}

# job.failed
{
  "job_id": "6f9c1e2a-...",
  "status": "error",
  "error": "what went wrong"
}

Respond with any 2xx to acknowledge. On anything else we retry after 5 seconds, 30 seconds, and 5 minutes, then drop the event, so polling remains your fallback. The URL must be a public http(s) endpoint: localhost and private network addresses are rejected at submit time. Requests are unsigned for now; put a secret in your URL path or query string if you need to verify the sender.

Missing something?

If the API is missing something you need, tell me. It shapes what gets built first.