PDF to EPUB REST API: curl, Webhooks, and Batch Conversion

June 12, 2026  ·  7 min read

The toolkit.bot API converts PDFs to EPUB programmatically — from any language, any platform. Here's a complete reference with curl examples, polling, webhooks, and batch patterns.

Authentication

All API requests require a Bearer token. Get your API key at toolkit.bot/account after signing in.

export TOOLKIT_API_KEY="tk_live_your_key_here"

Submit a Conversion Job

# Upload a PDF and start conversion
curl -X POST https://toolkit.bot/api/v1/convert   -H "Authorization: Bearer $TOOLKIT_API_KEY"   -F "file=@document.pdf"   -F "output_format=epub3"

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

Poll for Job Status

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

# While processing
{"job_id":"job_8f3a2c1d","status":"processing","progress":45}

# When complete
{
  "job_id": "job_8f3a2c1d",
  "status": "complete",
  "download_url": "https://toolkit.bot/api/v1/files/abc123.epub",
  "expires_at": "2026-06-13T10:00:00Z"
}

Download the Result

curl -L   -H "Authorization: Bearer $TOOLKIT_API_KEY"   "https://toolkit.bot/api/v1/files/abc123.epub"   -o output.epub

Shell Script: Submit, Poll, Download

#!/bin/bash
set -e
API="https://toolkit.bot/api/v1"
KEY="$TOOLKIT_API_KEY"
FILE="$1"

# Submit
JOB_ID=$(curl -sf -X POST "$API/convert"   -H "Authorization: Bearer $KEY"   -F "file=@$FILE" -F "output_format=epub3"   | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")

echo "Job: $JOB_ID"

# Poll
while true; do
  STATUS=$(curl -sf "$API/jobs/$JOB_ID"     -H "Authorization: Bearer $KEY"     | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['status'])")
  echo "Status: $STATUS"
  [ "$STATUS" = "complete" ] && break
  [ "$STATUS" = "failed" ] && exit 1
  sleep 3
done

# Download
DOWNLOAD=$(curl -sf "$API/jobs/$JOB_ID"   -H "Authorization: Bearer $KEY"   | python3 -c "import sys,json; print(json.load(sys.stdin)['download_url'])")
curl -sfL -H "Authorization: Bearer $KEY" "$DOWNLOAD"   -o "${FILE%.pdf}.epub"
echo "Done: ${FILE%.pdf}.epub"

Batch Conversion (Multiple Files)

#!/bin/bash
# Convert all PDFs in a folder
for pdf in /input/*.pdf; do
  bash convert.sh "$pdf" &
done
wait
echo "All done"

Webhook Notifications

Instead of polling, register a webhook URL to receive a POST when a job completes:

# Submit with webhook
curl -X POST https://toolkit.bot/api/v1/convert   -H "Authorization: Bearer $TOOLKIT_API_KEY"   -F "file=@document.pdf"   -F "output_format=epub3"   -F "webhook_url=https://yourapp.com/hooks/epub-done"

# Webhook payload on completion
{
  "event": "job.complete",
  "job_id": "job_8f3a2c1d",
  "download_url": "https://toolkit.bot/api/v1/files/abc123.epub",
  "expires_at": "2026-06-13T10:00:00Z"
}

Rate Limits and File Limits

Rate limit headers are included in every response: X-RateLimit-Remaining and X-RateLimit-Reset.

Error Codes