PDF to EPUB with curl — REST API Quick Start

June 12, 2026  ·  6 min read

The toolkit.bot REST API converts PDF to EPUB in three curl commands. No SDK, no library, no account setup beyond an API key. This guide is for developers who want to test the API quickly or integrate it into shell scripts and CI pipelines.

The three commands

# 1. Upload PDF and get a job ID
curl -X POST https://toolkit.bot/api/v1/jobs   -H "Authorization: Bearer $TOOLKIT_API_KEY"   -F "file=@document.pdf"   | tee /tmp/upload.json

# 2. Poll until status is "done"
curl https://toolkit.bot/api/v1/jobs/JOB_ID   -H "Authorization: Bearer $TOOLKIT_API_KEY"

# 3. Download the EPUB
curl -L "DOWNLOAD_URL"   -H "Authorization: Bearer $TOOLKIT_API_KEY"   -o document.epub

Replace JOB_ID with the job_id from step 1 and DOWNLOAD_URL with the download_url from step 2.

Step 1: Upload the PDF

curl -X POST https://toolkit.bot/api/v1/jobs   -H "Authorization: Bearer $TOOLKIT_API_KEY"   -F "file=@/path/to/document.pdf"

Response (HTTP 202):

{
  "job_id": "abc123def456",
  "status": "queued",
  "created_at": "2026-06-12T10:00:00Z"
}

Save the job_id — you need it for polling.

Step 2: Poll for job status

curl https://toolkit.bot/api/v1/jobs/abc123def456   -H "Authorization: Bearer $TOOLKIT_API_KEY"

While processing, the response looks like:

{
  "job_id": "abc123def456",
  "status": "processing",
  "progress": 0.6
}

When done:

{
  "job_id": "abc123def456",
  "status": "done",
  "download_url": "https://toolkit.bot/api/v1/jobs/abc123def456/download",
  "expires_at": "2026-06-13T10:00:00Z"
}

Poll every 3–5 seconds. Most PDFs finish in 10–30 seconds; scanned PDFs may take up to 2 minutes.

Step 3: Download the EPUB

curl -L "https://toolkit.bot/api/v1/jobs/abc123def456/download"   -H "Authorization: Bearer $TOOLKIT_API_KEY"   -o document.epub

The -L flag follows redirects. The downloaded file is a valid EPUB3 archive, readable by any compliant reader.

One-shot shell script

The script below handles the full flow — upload, poll, download — without any manual steps:

#!/usr/bin/env bash
set -euo pipefail

PDF_FILE="${1:?Usage: convert.sh file.pdf}"
API_KEY="${TOOLKIT_API_KEY:?Set TOOLKIT_API_KEY}"
API="https://toolkit.bot/api/v1"

echo "Uploading $PDF_FILE..."
UPLOAD=$(curl -sf -X POST "$API/jobs"   -H "Authorization: Bearer $API_KEY"   -F "file=@$PDF_FILE")
JOB_ID=$(echo "$UPLOAD" | grep -o '"job_id":"[^"]*"' | cut -d'"' -f4)
echo "Job ID: $JOB_ID"

echo "Waiting for conversion..."
for i in $(seq 1 60); do
  sleep 4
  STATUS_JSON=$(curl -sf "$API/jobs/$JOB_ID"     -H "Authorization: Bearer $API_KEY")
  STATUS=$(echo "$STATUS_JSON" | grep -o '"status":"[^"]*"' | cut -d'"' -f4)
  echo "  [$i] $STATUS"
  if [ "$STATUS" = "done" ]; then
    DL_URL=$(echo "$STATUS_JSON" | grep -o '"download_url":"[^"]*"' | cut -d'"' -f4)
    break
  fi
  if [ "$STATUS" = "failed" ]; then
    echo "Conversion failed: $STATUS_JSON" >&2
    exit 1
  fi
done

OUTPUT="${PDF_FILE%.pdf}.epub"
echo "Downloading to $OUTPUT..."
curl -sfL "$DL_URL"   -H "Authorization: Bearer $API_KEY"   -o "$OUTPUT"
echo "Done: $OUTPUT"

Usage: chmod +x convert.sh && TOOLKIT_API_KEY=tk_xxx ./convert.sh paper.pdf

This script works on Linux, macOS, and Windows WSL. It requires only bash and curl — no Python, no Node, no dependencies.

Using jq for cleaner JSON parsing

If you have jq installed, replace the grep-based parsing with proper JSON extraction:

JOB_ID=$(echo "$UPLOAD" | jq -r .job_id)
STATUS=$(curl -sf "$API/jobs/$JOB_ID"   -H "Authorization: Bearer $API_KEY" | jq -r .status)
DL_URL=$(curl -sf "$API/jobs/$JOB_ID"   -H "Authorization: Bearer $API_KEY" | jq -r .download_url)

FAQ

Where do I get an API key?

Sign up at toolkit.bot/api. The free tier includes enough conversions to test and build a prototype.

What file size limit does the API have?

50 MB on the free tier. The API returns HTTP 413 if the file exceeds the limit.

How do I pass extra options (e.g. OCR language)?

Add form fields to the upload request: -F "ocr_lang=fra" for French OCR, -F "preserve_images=true" to keep image quality. See the full API docs at toolkit.bot/api.

Can I use curl on Windows?

Yes. Windows 10 and 11 include curl natively. The script above also works in Windows Subsystem for Linux (WSL). On PowerShell, use Invoke-RestMethod instead of curl for best compatibility.

How do I batch-convert multiple PDFs?

Loop over files in bash: for f in *.pdf; do ./convert.sh "$f"; done. For parallel processing, use xargs or parallel to run multiple jobs concurrently.