Conversions & jobs

Beyond the instant tools, the API exposes an asynchronous conversion pipeline: you enqueue a job, then poll it until the result is ready. This path is account-scoped, keeps a history, and suits longer-running work.

All three endpoints require an API key.

1. Enqueue a conversion

POST /api/v1/convert accepts JSON referencing a source_file and the target_format, and returns a job in the queued state:

curl -X POST https://bastosconvert.com/api/v1/convert \
  -H "Authorization: Bearer bsc_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "source_file": "5e9d…-uuid", "target_format": "png" }'

The conversion work runs off the request thread, so /convert returns immediately with a job to track — it does not block on the conversion.

2. Poll the job

GET /api/v1/conversion_jobs/{id} returns a single job's current state. Poll it until it reaches a terminal state (then read the output reference):

curl https://bastosconvert.com/api/v1/conversion_jobs/<id> \
  -H "Authorization: Bearer bsc_live_…"

Reads are owner-scoped — a key only sees its own account's jobs; requesting another account's job id returns 404.

3. List history

GET /api/v1/conversion_jobs lists your jobs, newest first — useful for dashboards and reconciliation:

curl https://bastosconvert.com/api/v1/conversion_jobs \
  -H "Authorization: Bearer bsc_live_…"

Instant vs. job-based — which to use

• One file, want it now? Use an instant tool — no key, no polling, the file comes back in the response.
• Need history, account scoping, or the queued pipeline? Use /convert + /conversion_jobs.

See the API reference (sidebar) for the exact job schema and fields.