API Documentation

Integrate PDF Master tools into your applications with our REST API.

Getting Started

The PDF Master API allows you to programmatically access all PDF tools available on the platform. To get started, you'll need an API key.

1. Get Your API Key

Generate an API key from your API Keys page. You'll receive:

  • API Key: Used to identify your account (e.g., pm_abc123...)
  • API Secret: Used for authentication (keep this secure!)

2. Authentication

Include your API key in the request header:

Authorization: Bearer your_api_key_here

Or use both key and secret for enhanced security:

X-API-Key: your_api_key_here X-API-Secret: your_api_secret_here

3. Base URL

https://pdfmaster.co.za/api/v1

Rate Limits

API rate limits protect the service from abuse and ensure fair usage for all users. Limits are based on your subscription plan:

Burst Limits (Short-term)

These limits prevent sudden spikes in API usage:

Plan Per Minute Per Hour
Free 5 requests 30 requests
Pro 30 requests 200 requests
Ultra 100 requests 1,000 requests

Quota Limits (Long-term)

These limits define your total API usage allowance:

Plan Daily Limit Monthly Limit
Free 50 requests 500 requests
Pro 100 requests 3,000 requests
Ultra 500 requests 15,000 requests

Rate Limit Headers

Every API response includes headers showing your current limit status:

# Burst Limits (short-term) X-RateLimit-Limit-Minute: 30 X-RateLimit-Remaining-Minute: 29 X-RateLimit-Limit-Hourly: 200 X-RateLimit-Remaining-Hourly: 199 # Quota Limits (long-term) X-RateLimit-Limit-Daily: 500 X-RateLimit-Remaining-Daily: 499 X-RateLimit-Limit-Monthly: 10000 X-RateLimit-Remaining-Monthly: 9999

Rate Limit Exceeded

When you exceed any rate limit, you'll receive a 429 Too Many Requests response:

{ "success": false, "error": "Rate limit exceeded: minute limit reached", "retry_after": 45 }

The Retry-After header indicates how many seconds to wait before making another request.

API Endpoints

PDF Operations

POST /api/v1/pdf/merge

Merge multiple PDF files into a single document.

Request Body (multipart/form-data)

Parameter Type Required Description
files[] file required PDF files to merge (minimum 2)
output_name string optional Output filename (default: merged.pdf)

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/merge" \ -H "Authorization: Bearer your_api_key" \ -F "files[]=@document1.pdf" \ -F "files[]=@document2.pdf"

Note: Download links expire after 1 hour.

POST /api/v1/pdf/split

Split a PDF into multiple files by page ranges.

ParameterTypeRequiredDescription
filefilerequiredPDF file to split
pagesstringrequiredPage ranges (e.g., "1-3,5,7-10")

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/split" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.pdf" \ -F "pages=1-3,5,7-10"

Note: Download links expire after 1 hour.

POST /api/v1/pdf/watermark

Add a text watermark to all pages of a PDF.

ParameterTypeRequiredDescription
filefilerequiredPDF file
textstringrequiredWatermark text
opacityfloatoptional0.0 to 1.0 (default: 0.3)
angleintoptionalRotation angle (default: 45)
font_sizeintoptionalFont size (default: 48)
colorstringoptionalHex color (default: #cccccc)

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/watermark" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.pdf" \ -F "text=CONFIDENTIAL" \ -F "opacity=0.3"

Note: Download links expire after 1 hour.

POST /api/v1/pdf/compress

Compress a PDF file to reduce file size.

ParameterTypeRequiredDescription
filefilerequiredPDF file to compress
qualitystringoptionallow, medium, or high (default: medium)

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/compress" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.pdf" \ -F "quality=medium"

Note: Download links expire after 1 hour.

POST /api/v1/pdf/metadata

Update PDF document metadata (title, author, etc.).

ParameterTypeRequiredDescription
filefilerequiredPDF file
titlestringoptionalDocument title
authorstringoptionalAuthor name
subjectstringoptionalSubject
keywordsstringoptionalKeywords

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/metadata" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.pdf" \ -F "title=My Document" \ -F "author=John Doe"

Note: Download links expire after 1 hour.

POST /api/v1/pdf/page-numbers

Add page numbers to a PDF document.

ParameterTypeRequiredDescription
filefilerequiredPDF file
positionstringoptionalbottom-center, bottom-left, bottom-right, etc.
formatstringoptionalFormat string (default: "Page {n} of {total}")
start_pageintoptionalStarting page number (default: 1)

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/page-numbers" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.pdf" \ -F "format=Page {n} of {total}"

Note: Download links expire after 1 hour.

POST /api/v1/pdf/generate

Generate a PDF from text content.

ParameterTypeRequiredDescription
contentstringrequiredText content for the PDF
titlestringoptionalDocument title (default: "Generated Document")
page_sizestringoptionalPage size: A4, Letter, etc. (default: A4)
orientationstringoptionalP or L (default: P)
font_sizeintoptionalFont size (default: 12)

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/generate" \ -H "Authorization: Bearer your_api_key" \ -d "content=This is my PDF content" \ -d "title=My Document"

Note: Download links expire after 1 hour.

POST /api/v1/pdf/reorder

Reorder and rotate PDF pages.

ParameterTypeRequiredDescription
filefilerequiredPDF file to reorder
orderstringrequiredPage order (e.g., "3,1,2,4")
rotationintoptionalRotation angle: 0, 90, 180, or 270 (default: 0)

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/reorder" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.pdf" \ -F "order=3,1,2,4" \ -F "rotation=90"

Note: Download links expire after 1 hour.

POST /api/v1/pdf/to-images

Convert PDF pages to image files.

ParameterTypeRequiredDescription
filefilerequiredPDF file to convert
formatstringoptionalImage format: png, jpg, jpeg (default: png)
dpiintoptionalResolution in DPI, 72-300 (default: 150)

Note: Returns array of image download URLs, one per page.

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/to-images" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.pdf" \ -F "format=png" \ -F "dpi=150"

Note: Returns array of image download URLs, one per page. Download links expire after 1 hour.

Advanced PDF Operations

POST /api/v1/pdf/compress-pro

Advanced PDF compression using Ghostscript with multiple quality presets for maximum file size reduction.

ParameterTypeRequiredDescription
filefilerequiredPDF file to compress
qualitystringoptionalscreen (lowest), ebook (medium), printer (high), prepress (highest quality). Default: ebook

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/compress-pro" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.pdf" \ -F "quality=ebook"

Note: Provides superior compression compared to standard compress. Download links expire after 1 hour.

POST /api/v1/pdf/to-pdfa

Convert PDF to PDF/A format for long-term archival and compliance with archiving standards.

ParameterTypeRequiredDescription
filefilerequiredPDF file to convert

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/to-pdfa" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.pdf"

Note: Converts to PDF/A-1b standard. Download links expire after 1 hour.

POST /api/v1/pdf/grayscale

Convert a color PDF to grayscale (black and white). Useful for printing or reducing file size.

ParameterTypeRequiredDescription
filefilerequiredPDF file to convert

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/grayscale" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.pdf"

Note: Download links expire after 1 hour.

POST /api/v1/pdf/repair

Attempt to repair corrupted or damaged PDF files by rebuilding the document structure.

ParameterTypeRequiredDescription
filefilerequiredPDF file to repair

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/repair" \ -H "Authorization: Bearer your_api_key" \ -F "file=@corrupted.pdf"

Note: Not all corrupted PDFs can be repaired. Download links expire after 1 hour.

POST /api/v1/pdf/flatten

Flatten PDF layers and annotations, making form fields non-editable and merging all layers into a single layer.

ParameterTypeRequiredDescription
filefilerequiredPDF file to flatten

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/flatten" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.pdf"

Note: Useful for finalizing filled forms. Download links expire after 1 hour.

POST /api/v1/pdf/optimize-web

Optimize PDF for fast web viewing (linearization). Enables progressive loading for web browsers.

ParameterTypeRequiredDescription
filefilerequiredPDF file to optimize

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/optimize-web" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.pdf"

Note: Creates a linearized PDF for faster first-page display. Download links expire after 1 hour.

POST /api/v1/pdf/protect

Add password protection to a PDF file. Encrypt the PDF with user and owner passwords, and control permissions like printing, copying, and modification.

ParameterTypeRequiredDescription
filefilerequiredPDF file to protect
user_passwordstringrequiredPassword required to open/view the PDF
owner_passwordstringoptionalPassword for full access (print, edit, etc.). Defaults to user_password if not specified.
permissionsarrayoptionalJSON array of allowed permissions: print, copy, modify, annotate. Empty array means all permissions denied.

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/protect" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.pdf" \ -F "user_password=secret123" \ -F "owner_password=admin456" \ -F 'permissions=["print","copy"]'

Response

{ "success": true, "data": { "message": "PDF protected with password", "download_url": "https://pdfmaster.co.za/api/v1/download/abc123...", "permissions": ["print", "copy"], "expires_in": 3600 } }

Note: The protected PDF will require the user password to open. The owner password grants full editing permissions. Download links expire after 1 hour.

Conversion Operations

POST /api/v1/convert/word-to-pdf

Convert a Word document (.doc, .docx) to PDF.

ParameterTypeRequiredDescription
filefilerequiredWord document to convert

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/convert/word-to-pdf" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.docx"

Note: Download links expire after 1 hour.

POST /api/v1/convert/image-to-pdf

Convert images to a PDF document.

ParameterTypeRequiredDescription
images[]filerequiredImage files (JPG, PNG, GIF, WebP)
page_sizestringoptionalPage size (A4, Letter, etc.)
orientationstringoptionalportrait or landscape

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/convert/image-to-pdf" \ -H "Authorization: Bearer your_api_key" \ -F "images[]=@image1.jpg" \ -F "images[]=@image2.png"

Note: Download links expire after 1 hour.

POST /api/v1/convert/html-to-pdf

Convert HTML content to PDF. Supports single page or multi-page PDF generation.

Parameters

ParameterTypeRequiredDescription
htmlstringrequired*HTML content for single page conversion
html_pagesarrayoptionalJSON array of HTML strings OR array of {html, title} objects for multi-page PDF
cssstringoptionalCSS styles to apply to all pages
page_sizestringoptionalA4, Letter, Legal, A3 (default: A4)
orientationstringoptionalportrait or landscape (default: portrait)
margin_topintoptionalTop margin in mm (default: 16)
margin_bottomintoptionalBottom margin in mm (default: 16)
margin_leftintoptionalLeft margin in mm (default: 15)
margin_rightintoptionalRight margin in mm (default: 15)

* Either html OR html_pages is required.

Example: Single Page

curl -X POST "https://pdfmaster.co.za/api/v1/convert/html-to-pdf" \ -H "Authorization: Bearer your_api_key" \ -d "html=<h1>Hello World</h1><p>This is a test.</p>" \ -d "page_size=A4"

Example: Multi-Page PDF

curl -X POST "https://pdfmaster.co.za/api/v1/convert/html-to-pdf" \ -H "Authorization: Bearer your_api_key" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d 'html_pages=[{"html":"<h1>Page 1</h1><p>Content...</p>","title":"Introduction"},{"html":"<h1>Page 2</h1><p>More content...</p>","title":"Details"}]' \ -d "css=body{font-family:Arial;}"

Response

{ "success": true, "data": { "file_url": "https://pdfmaster.co.za/api/v1/download/abc123...", "filename": "converted_1234567890.pdf", "expires_at": "2024-01-15T12:00:00+02:00", "page_count": 2, "file_size": 25600 } }

Note: Download links expire after 1 hour. The page_count field shows the number of pages in the generated PDF.

POST /api/v1/convert/excel-to-pdf

Convert Excel spreadsheet (.xls, .xlsx) to PDF.

ParameterTypeRequiredDescription
filefilerequiredExcel file to convert (.xls or .xlsx)

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/convert/excel-to-pdf" \ -H "Authorization: Bearer your_api_key" \ -F "file=@spreadsheet.xlsx"

Note: Download links expire after 1 hour.

POST /api/v1/convert/odt-to-pdf

Convert ODT (OpenDocument Text) document to PDF.

ParameterTypeRequiredDescription
filefilerequiredODT file to convert

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/convert/odt-to-pdf" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.odt"

Note: Download links expire after 1 hour.

POST /api/v1/convert/rtf-to-pdf

Convert RTF (Rich Text Format) document to PDF.

ParameterTypeRequiredDescription
filefilerequiredRTF file to convert

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/convert/rtf-to-pdf" \ -H "Authorization: Bearer your_api_key" \ -F "file=@document.rtf"

Note: Download links expire after 1 hour.

POST /api/v1/pdf/barcode

Generate barcodes or QR codes in PDF format. Supports single codes, batch creation (multiple codes), and overlay on existing PDFs.

Basic Parameters

ParameterTypeRequiredDescription
datastringrequired*Single barcode data OR newline-separated batch data. Use "data|label" format for custom labels.
batch_dataarrayoptionalJSON array of {data, label} objects for batch mode
typestringoptionalQRCODE, C128, C39, EAN13, EAN8, UPCA, UPCE, I25, CODABAR (default: QRCODE)
widthintoptionalBarcode width in mm, 20-180 (default: 60)
heightintoptionalBarcode height in mm, 20-180 (default: 60)
repeat_countintoptionalDuplicate single barcode this many times, 1-50 (default: 1). Use with layout options for grid placement.

Layout Options (for batch mode)

ParameterTypeRequiredDescription
layoutstringoptionalgrid, inline, or single (default: grid)
columnsintoptionalNumber of columns for grid layout, 1-6 (default: 3)
spacingintoptionalSpacing between barcodes in mm, 2-30 (default: 10)
show_labelsbooloptionalShow labels under barcodes (default: true)
page_sizestringoptionalA4, LETTER, A3, A5 (default: A4)
orientationstringoptionalportrait or landscape (default: portrait)

PDF Overlay Options

ParameterTypeRequiredDescription
pdffileoptionalExisting PDF to overlay barcodes on
overlay_positionstringoptionaltop-left, top-center, top-right, center-left, center, center-right, bottom-left, bottom-center, bottom-right (default: top-right)
overlay_pagestringoptionalall, first, last, or page range like "1,3,5-10" (default: all)
overlay_xintoptionalCustom X position in mm (overrides overlay_position)
overlay_yintoptionalCustom Y position in mm (overrides overlay_position)

Example: Single Barcode

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/barcode" \ -H "Authorization: Bearer your_api_key" \ -d "data=https://example.com" \ -d "type=QRCODE"

Example: Repeated Barcodes (12 copies in 4-column grid)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/barcode" \ -H "Authorization: Bearer your_api_key" \ -d "data=https://example.com" \ -d "repeat_count=12" \ -d "layout=grid" \ -d "columns=4"

Example: Batch Barcodes (newline-separated)

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/barcode" \ -H "Authorization: Bearer your_api_key" \ -d "data=SKU001|Product A SKU002|Product B SKU003|Product C" \ -d "layout=grid" \ -d "columns=3"

Example: Overlay on Existing PDF

curl -X POST "https://pdfmaster.co.za/api/v1/pdf/barcode" \ -H "Authorization: Bearer your_api_key" \ -F "pdf=@document.pdf" \ -F "data=QR-CODE-DATA" \ -F "overlay_position=bottom-right" \ -F "overlay_page=first"

Response

{ "success": true, "data": { "file_url": "https://pdfmaster.co.za/api/v1/download/abc123...", "filename": "barcode_1234567890.pdf", "expires_at": "2024-01-15T12:00:00+02:00", "barcode_count": 3, "layout": "grid", "file_size": 15360 } }

Note: Download links expire after 1 hour. The barcode_count field shows how many barcodes were generated.

GET /api/v1/download/{token}

Download a processed file using the token from the API response.

ParameterTypeRequiredDescription
tokenstringrequiredDownload token from API response (URL parameter)

Example Request (cURL)

curl -X GET "https://pdfmaster.co.za/api/v1/download/abc123..." \ -H "Authorization: Bearer your_api_key" \ -o "output.pdf"

Note: Download links expire after 1 hour and are single-use only.

Utility Tools

POST /api/v1/utility/invoice

Generate a professional invoice PDF with customizable templates, items, taxes, and discounts.

ParameterTypeRequiredDescription
company_namestringrequiredYour company/business name
client_namestringrequiredClient/buyer name
itemsarrayrequiredJSON array of {description, quantity, price} objects
templatestringoptionalTemplate: modern, classic, minimal, corporate (default: modern)
currencystringoptionalCurrency code: USD, EUR, GBP, ZAR, etc. (default: USD)
company_addressstringoptionalCompany address
company_emailstringoptionalCompany email
company_phonestringoptionalCompany phone
company_tax_idstringoptionalTax ID / VAT number
client_addressstringoptionalClient address
client_emailstringoptionalClient email
invoice_numberstringoptionalInvoice number (auto-generated if not provided)
invoice_datestringoptionalInvoice date (YYYY-MM-DD)
due_datestringoptionalPayment due date (YYYY-MM-DD)
tax_ratefloatoptionalTax percentage 0-100
discount_typestringoptional"percentage" or "fixed"
discount_valuefloatoptionalDiscount value
notesstringoptionalAdditional notes
payment_termsstringoptionalPayment terms
bank_detailsstringoptionalBank details for payment

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/utility/invoice" \ -H "Authorization: Bearer your_api_key" \ -d "company_name=Acme Corp" \ -d "client_name=John Doe" \ -d 'items=[{"description":"Web Development","quantity":10,"price":100}]' \ -d "tax_rate=15"

Note: Download links expire after 1 hour.

POST /api/v1/utility/weather

Generate a weather forecast PDF report for any location worldwide.

ParameterTypeRequiredDescription
latitudefloatrequiredLocation latitude (-90 to 90)
longitudefloatrequiredLocation longitude (-180 to 180)
location_namestringoptionalDisplay name for the location
unitsstringoptional"metric" or "imperial" (default: metric)
daysintoptionalForecast days 1-14 (default: 7)

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/utility/weather" \ -H "Authorization: Bearer your_api_key" \ -d "latitude=-33.9249" \ -d "longitude=18.4241" \ -d "location_name=Cape Town, South Africa" \ -d "days=7"

Note: Weather data provided by Open-Meteo. Download links expire after 1 hour.

POST /api/v1/utility/movie

Generate a movie information PDF report using TMDB (The Movie Database).

ParameterTypeRequiredDescription
movie_idintrequiredTMDB movie ID
include_castbooloptionalInclude cast information (default: true)
include_reviewsbooloptionalInclude reviews (default: false)

Example Request (cURL)

curl -X POST "https://pdfmaster.co.za/api/v1/utility/movie" \ -H "Authorization: Bearer your_api_key" \ -d "movie_id=550" \ -d "include_cast=true"

Note: Movie data provided by TMDB. Download links expire after 1 hour.

Response Format

All successful API responses return:

{ "success": true, "data": { "file_url": "https://pdfmaster.co.za/api/v1/download/abc123...", "filename": "merged_1234567890.pdf", "expires_at": "2024-01-15T12:00:00+00:00", "file_size": 102400 } }

Note: All download links expire after 1 hour. The expires_at field in the response indicates when the download link will expire.

Error Handling

The API uses standard HTTP status codes:

Status Code Description
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
403Forbidden - API access not enabled
429Too Many Requests - Rate limit exceeded
500Server Error

Error Response Format

{ "success": false, "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "You have exceeded your daily API limit", "details": { "limit": 500, "used": 500, "resets_at": "2024-01-16T00:00:00Z" } } }

Need Help?

Contact our support team for API integration assistance.

Contact Support