Docs

API quickstart

Four requests: create a job, upload your file, start the conversion, download the result. No SDK required — it's plain HTTP and JSON. Anonymous use is free within the Free plan limits.

01See what's supported

Every conversion pair the engine supports, machine-readable.

$ curl https://api-staging.converting.app/v1/formats

02 Create a job

Declare the source and target format. You get back a job id and a time-limited upload URL.

$ curl -X POST https://api-staging.converting.app/v1/jobs \
    -H "Content-Type: application/json" \
    -d '{"source_format":"csv","target_format":"json","filename":"data.csv"}'
# → {"id":"job_…","upload_method":"PUT","upload_url":"https://…","upload_headers":{…}}

03 Upload, then start

Upload the file to storage with the returned method, URL, and headers.

$ curl -X PUT "$UPLOAD_URL" -H "Content-Type: text/csv" --data-binary @data.csv
$ curl -X POST https://api-staging.converting.app/v1/jobs/$JOB_ID/start

04 Poll and download

Poll until status is done, then follow the artifact download URLs. Archive extraction returns one artifact per file.

$ curl https://api-staging.converting.app/v1/jobs/$JOB_ID
# → {"status":"done","artifacts":[{"kind":"output","filename":"output.json","download_url":"https://…"}]}

Error codes

problem+json

Errors come back as RFC 7807 problem+json with a stable code field — match on the code, not the message.

unsupported_pairThe source → target combination isn't supported. Check GET /v1/formats.

too_largeThe uploaded file exceeds the 1 GB limit.

too_large_for_formatFully-parsed formats (YAML, TOML, XML, XLSX) are limited to 64 MB.

corrupt_inputThe file couldn't be parsed as the declared source format.

archive_too_largeThe archive expands beyond the 512 MB extraction limit.

archive_entry_limitThe archive contains more than 1,000 files.

archive_traversalThe archive contains unsafe paths or links and was rejected.

retries_exhaustedA transient failure persisted through retries. Safe to retry the job.

Building an agent?

workos auth.md

Agents don't need this page. Discovery, registration, and token exchange are fully machine-readable — start from /auth.md or any 401 response.