Convert API quickstart

Convert API quickstart

The Gevell Convert API turns a PDF into a tagged accessible PDF with its PDF/UA-1 conformance report and, if you ask for it, accessible HTML. This page is a short guide to the flow. The complete endpoint reference, with every field and error, is in the Convert API reference.

Before you start

• Billing. Converting is billed per page at your account’s PDF rate, the same as in the app (see Controlling costs). Only the estimate is free. The cost is reserved when you start, so a start your balance can’t cover is refused with a 402 error before anything is stored.
• Base URL. https://api.gevell.com
• Response format. Successful responses look like { "success": true, "data": ... }. Errors look like { "success": false, "error": { "code", "message", "details" } }.

1. Create an API key

1. Sign in at pdf.gevell.com, open Settings, and choose the API keys tab.
2. Choose Create key, give it a name, and choose Create.
3. Copy the key right away. It is shown only once.

You can have up to 10 active keys; revoke one to make room. A revoked key stops working, and keys also stop working if the account is deleted. Keep keys secret and out of client-side code.

Send the key in the X-API-Key header on every request.

export GEVELL_API_KEY="your-key-here"

2. Estimate the cost (free)

curl -X POST https://api.gevell.com/api/v1/convert/estimate \
  -H "X-API-Key: $GEVELL_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

The response reports the page count, the price at your account’s rate, your available balance, and whether you can afford the conversion. Estimates are limited to 120 requests per hour per account.

3. Start the conversion

curl -X POST "https://api.gevell.com/api/v1/convert?outputs=pdf,html&fileName=report.pdf" \
  -H "X-API-Key: $GEVELL_API_KEY" \
  -H "Content-Type: application/pdf" \
  -H "Idempotency-Key: report-2026-q3-001" \
  --data-binary @report.pdf

• outputs chooses what to deliver: pdf, conformance, and html. The default is the tagged PDF and its conformance report. Add html for the accessible HTML.
• Idempotency-Key (8 to 200 characters) makes the call safe to repeat. The same key from the same account always refers to one file and one charge, so a client that crashed can resume by repeating the call. Keys are remembered for 24 hours.
• Other ways to send the file. Send JSON instead of the raw file, naming either a public fileUrl or an inputKey from a staged upload. The reference has the details.

A successful start answers 202 with a fileId.

4. Check progress

curl https://api.gevell.com/api/v1/convert/FILE_ID \
  -H "X-API-Key: $GEVELL_API_KEY"

Poll no more than once every 12 seconds, until done is true.

5. Get the results

curl https://api.gevell.com/api/v1/convert/FILE_ID/result \
  -H "X-API-Key: $GEVELL_API_KEY"

The response includes signed download links for each output you asked for, with their expiry times, plus the conformance summary. If you call it before the work is finished you get 409 NOT_READY; wait and try again. If the conversion failed, you get 422.

To stop a conversion that is in progress, call POST /api/v1/convert/FILE_ID/cancel. The reserved cost is released and nothing is charged.

Limits and errors

• File size. Up to 25 MB through api.gevell.com. Through api-pdf.gevell.com the limit is about 4.5 MB of PDF; for larger files, stage the upload and start with an inputKey.
• Common errors. 401 missing or invalid key. 402 balance too low (the details state how much is needed). 413 file too large. 422 the PDF is encrypted or unreadable. 429 an estimate limit or one of your own spend limits was reached. 503 a temporary problem, so retry.
• Spend limits. The daily and monthly limits you set in Settings apply to API conversions too. See Billing & credits.

More

• Convert API reference
• VPAT Parser API