SayPDF API Documentation

Complete API reference for integrating PDF conversion services into your applications

View Interactive Swagger API Docs

Quick Start

1
Get Your API Key

Sign up for a subscription plan and create an API key from your dashboard.

2
Make Your First Request

Use your API key to authenticate and convert your first file.

3
Sandbox First

Use the X-Sandbox header to test your integration without burning credits.

Authentication

API Key Authentication

All API v1 endpoints require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Note: Replace YOUR_API_KEY with your actual API key. Keep your API key secure and never expose it in client-side code.

Sandbox Mode

Developers can test the API without consuming credits by sending a specific header. In sandbox mode, the API validates your request and returns a mock successful response with a placeholder file.

X-Sandbox: true

Great for CI/CD pipelines and local development.

API Endpoints

POST

/api/v1/convert

Convert a PDF or image file to various formats. Usage is calculated based on the number of PDF pages processed.

Request
POST /api/v1/convert Content-Type: multipart/form-data Authorization: Bearer YOUR_API_KEY file: [binary file] typeConvert: pdf_to_word lang: eng (optional) imageFormat: png (optional) webhookUrl: https://... (optional) clientReference: batch_001 (optional) priority: high (optional - jump the queue)
Response
{ "success": true, "fileId": "uuid", "url": "https://...", "previewUrl": "https://...", "pages": 10 }
GET

/api/v1/convert/:id/status

Check the status of a conversion.

Example
GET /api/v1/convert/123e4567-e89b-12d3-a456-426614174000/status Authorization: Bearer YOUR_API_KEY
GET

/api/v1/convert/:id/result

Get the conversion result with download URL.

GET

/api/v1/usage

Get your API usage statistics and quota status.

GET

/api/v1/health

Get real-time system performance data, queue lengths, and worker status.

{ "status": "Optimal", "queue": { "waiting": 0, "active": 1 }, "averageProcessingTimeMs": 4200 }
GET

/api/v1/result/:id/thumbnail

Instantly retrieve a JPG thumbnail (300px width) of the first page of your conversion.

Code Examples

JavaScript/Node.js

const FormData = require('form-data'); const fs = require('fs'); const fetch = require('node-fetch'); const formData = new FormData(); formData.append('file', fs.createReadStream('document.pdf')); formData.append('typeConvert', 'pdf_to_word'); const response = await fetch('https://api.saypdf.com/api/v1/convert', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', ...formData.getHeaders() }, body: formData }); const result = await response.json(); console.log(result);

Python

import requests url = 'https://api.saypdf.com/api/v1/convert' headers = { 'Authorization': 'Bearer YOUR_API_KEY' } files = { 'file': open('document.pdf', 'rb') } data = { 'typeConvert': 'pdf_to_word' } response = requests.post(url, headers=headers, files=files, data=data) result = response.json() print(result)

cURL

curl -X POST https://api.saypdf.com/api/v1/convert \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "[email protected]" \ -F "typeConvert=pdf_to_word"

Conversion Types

PDF Conversions
  • pdf_to_word - PDF to Word
  • pdf_to_excel - PDF to Excel
  • pdf_to_ppt - PDF to PowerPoint
  • pdf_to_image - PDF to Images
  • text_from_pdf - Extract text from PDF
OCR Conversions
  • image_to_text - Image to Text
  • handwriting_to_text - Handwriting to Text
  • pdf_to_invoice - PDF Invoice Extraction
  • invoice_to_excel - Invoice to Excel

Pricing

Subscription Plans

Choose a monthly subscription plan that fits your needs:

  • Mini: $1.00/month - 100 pages/month
  • Basic: $5.00/month - 850 pages/month
  • Starter: $9.99/month - 2,000 pages/month
  • Professional: $29.99/month - 7,500 pages/month
  • Business: $99.99/month - 40,000 pages/month (3-day free trial)

See our pricing page for full details and feature comparison.

Pay As You Go with Credits

Flexible Credit Packages

Purchase credits and use them whenever you need. Perfect for occasional users or when you exceed your subscription limit. Credits never expire!

100
$10
~1,700 pages*
Credits
600
$50
+20% Bonus
~10,000 pages*
1,400
$100
+40% Bonus
~23,300 pages*
8,000
$500
+60% Bonus
~133,000 pages*
Credit Usage Details
Basic Conversions
PDF to Word, Excel, PowerPoint, HTML, etc.
0.06 credits/page (~$0.006/page)
Example: 100 pages = 6 credits
OCR Conversions
Image to Text, Handwriting, PDF OCR
0.12 credits/page (~$0.012/page)
Example: 100 pages = 12 credits
Complex Conversions
Invoice, Bank Statement processing
0.18 credits/page (~$0.018/page)
Example: 100 pages = 18 credits

Note: *Page estimates based on basic conversions. OCR and complex conversions use more credits per page.

Pricing: $10 = 100 credits (1 credit = $0.10). Credits are deducted based on the number of PDF pages processed.

Error Handling

Error Responses

All errors follow a consistent format:

{ "statusCode": 400, "message": "Error message", "error": "Bad Request" }
Common Status Codes
  • 400 - Bad Request (invalid parameters, quota exceeded)
  • 401 - Unauthorized (invalid or missing API key)
  • 404 - Not Found (file or resource not found)
  • 429 - Too Many Requests (rate limit exceeded)
  • 500 - Internal Server Error

Rate Limits

Rate limits are based on your subscription plan:

  • Basic: 100 requests/hour
  • Starter: 500 requests/hour
  • Professional: 2,000 requests/hour
  • Business: 10,000 requests/hour

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Support

Need Help?

We're here to help you integrate SayPDF into your application: