Convert a file
POST /v1/convert takes a PDF or image and starts a conversion.
curl -X POST "https://api.docbeast.com/v1/convert?wait=25&filename=list.pdf" \
-H "Authorization: Bearer dbk_live_..." \
--data-binary @list.pdfThe file
Send the file as the request body, or in a form field named file:
curl -X POST "https://api.docbeast.com/v1/convert?wait=25" \
-H "Authorization: Bearer dbk_live_..." \
-F "file=@list.pdf"PDF, PNG, JPEG, WebP, TIFF and HEIC files work, up to 25 MB. docbeast works out the type from the file's contents, so its name and Content-Type don't matter.
The file is checked before anything else, so an upload that's rejected doesn't use up any pages or free conversions.
Query parameters
| Parameter | Default | What it does |
|---|---|---|
mode | table | table keeps rows and columns, and leaves out text around a table. text reads the page as plain text. |
wait | 0 | Seconds to hold the request open for the result, up to 25. |
filename | None | A name for the file, used to name the downloads. |
You can also set the name with an x-filename header, and a form upload uses the name of the uploaded file. Paths are dropped from it and it's cut to 120 characters.
Responses
The body is a job in all of these.
| Status | Meaning |
|---|---|
200 | Finished within wait. downloads has the links. |
202 | Queued or still running. Check it with GET /v1/jobs/{id}. |
422 | The job failed within wait. Its error says why. |
Other statuses are errors, listed under Errors.
Long files
Each kind of access has a limit on pages per file, and only that many are converted, from the start of the file. The rest are reported in pages_skipped, so a 60-page PDF on a plan with a 50-page limit comes back with pages_converted: 50 and pages_skipped: 10. The limits are under Plans and limits.
An account that has fewer pages left this period than a file needs gets as many as it has left. A file can't start at all if there are no pages left.
What you're charged
Only pages that were read successfully count. A failed job costs nothing, and neither does a page that couldn't be read.