PDF.co

Overview

What it does

PDF.co provides 18 powerful tools for PDF processing, conversion, and automation. Extract text and data from PDFs, merge and split documents, add watermarks and passwords, convert HTML and images to PDF, generate and read barcodes, and perform OCR on scanned documents. All processing happens through a simple cloud API with credit-based pricing.

Use Cases

Document Workflows: Automate contract processing, invoice extraction, and report generation. Content Management: Convert web pages to PDFs, merge documents, and compress files. Security: Add password protection and watermarks. Data Extraction: OCR scanned documents, read barcodes, and extract structured data. Creative: Generate QR codes, add annotations, and batch process images.

Quick Start

Get your API key

Visit PDF.co Dashboard
Sign up for a free account (no credit card required)
Copy your API key from the dashboard

Free tier includes:

300 credits per month
Most operations cost 1-3 credits
Perfect for testing and light usage

Add to NimbleBrain Studio

Open NimbleBrain Studio
Navigate to MCP Servers in the sidebar
Find PDF.co in the Document Processing category
Click Enable
Paste your API key when prompted
Click Save

The server will connect automatically and show “Active” status.

Test your connection

Try this in Studio’s chat interface:

"Extract text from this PDF: https://example.com/sample.pdf"

You should see the 🔧 tool indicator appear, followed by the extracted text content. If successful, you’re ready to use all 18 PDF.co tools!

Available Tools

PDF.co provides 18 tools organized into 6 categories for comprehensive document processing.

PDF Conversion Tools

pdf_to_text

Extract text content from PDF documents with optional page range selection.Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL or base64 encoded PDF
pages	string	No	All pages	Page range (e.g., “1-3” or “1,3,5”)
async_mode	boolean	No	false	Process asynchronously for large files

Returns:

{
  "error": false,
  "url": "https://pdf.co/output.txt",
  "text": "Extracted text content...",
  "pageCount": 5,
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Extract text from pages 1-10 of this PDF: https://example.com/report.pdf"

pdf_to_json

Extract structured data from PDFs in JSON format, preserving document structure.Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL or base64 encoded PDF
pages	string	No	All pages	Page range to process

Returns:

{
  "error": false,
  "url": "https://pdf.co/output.json",
  "data": {
    "pages": [...],
    "text": "...",
    "structure": {...}
  },
  "pageCount": 5,
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Convert this PDF to structured JSON: https://example.com/invoice.pdf"

pdf_to_html

Convert PDF documents to HTML format with optional simple mode.Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL or base64 encoded PDF
pages	string	No	All pages	Page range to convert
simple	boolean	No	false	Use simple HTML mode (plain text)

Returns:

{
  "error": false,
  "url": "https://pdf.co/output.html",
  "html": "<html>...</html>",
  "pageCount": 5,
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Convert this PDF to HTML with simple formatting: https://example.com/document.pdf"

pdf_to_csv

Extract tables from PDF documents to CSV format for spreadsheet analysis.Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL or base64 encoded PDF
pages	string	No	All pages	Page range containing tables

Returns:

{
  "error": false,
  "url": "https://pdf.co/output.csv",
  "csv": "col1,col2,col3\nval1,val2,val3",
  "pageCount": 3,
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Extract the table from page 2 of this PDF to CSV: https://example.com/report.pdf"

PDF Manipulation Tools

pdf_merge

Combine multiple PDF documents into a single unified PDF file.Parameters:

Parameter	Type	Required	Default	Description
urls	array[string]	Yes	-	List of PDF URLs or base64 encoded PDFs
name	string	No	”merged.pdf”	Output filename
async_mode	boolean	No	false	Process asynchronously for large files

Returns:

{
  "error": false,
  "url": "https://pdf.co/merged.pdf",
  "pageCount": 15,
  "message": null
}

Credit Cost: 1 credit per request (regardless of number of PDFs)Example Usage:

"Merge these three PDFs into one: https://example.com/doc1.pdf, https://example.com/doc2.pdf, https://example.com/doc3.pdf"

pdf_split

Split PDF documents into separate pages or extract specific page ranges.Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL or base64 encoded PDF
pages	string	No	All pages	Page ranges to extract (e.g., “1-3,5-7”)
split_by_pages	boolean	No	false	Split into individual pages

Returns:

{
  "error": false,
  "urls": [
    "https://pdf.co/page1.pdf",
    "https://pdf.co/page2.pdf"
  ],
  "pageCount": 2,
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Split this PDF into individual pages: https://example.com/document.pdf"

pdf_rotate

Rotate pages in a PDF document by 90, 180, or 270 degrees.Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL or base64 encoded PDF
angle	integer	Yes	-	Rotation angle (90, 180, 270, or -90)
pages	string	No	All pages	Page range to rotate

Returns:

{
  "error": false,
  "url": "https://pdf.co/rotated.pdf",
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Rotate pages 1-5 by 90 degrees in this PDF: https://example.com/document.pdf"

pdf_compress

Reduce PDF file size with configurable compression levels.Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL or base64 encoded PDF
compression_level	string	No	”balanced”	Compression level: “low”, “balanced”, “high”, “extreme”

Returns:

{
  "error": false,
  "url": "https://pdf.co/compressed.pdf",
  "originalSize": 5242880,
  "compressedSize": 1048576,
  "compressionRatio": 80.0,
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Compress this PDF with high compression: https://example.com/large-file.pdf"

pdf_add_watermark

Add text watermarks or annotations to PDF pages with customizable styling.Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL or base64 encoded PDF
text	string	Yes	-	Watermark text
x	integer	No	100	X position in points
y	integer	No	100	Y position in points
font_size	integer	No	24	Font size in points
color	string	No	”FF0000”	Hex color without # (e.g., “FF0000” for red)
opacity	float	No	0.5	Opacity from 0.0 to 1.0
pages	string	No	”0-”	Page range (e.g., “0-” for all pages)
name	string	No	”watermarked.pdf”	Output filename

Returns:

{
  "error": false,
  "url": "https://pdf.co/watermarked.pdf",
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Add 'CONFIDENTIAL' watermark in red with 30% opacity to all pages of this PDF: https://example.com/document.pdf"

PDF Security Tools

pdf_protect

Add password protection to PDF documents with configurable permissions.Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL or base64 encoded PDF
owner_password	string	Yes	-	Owner password for full access
user_password	string	No	null	User password for restricted access
allow_print	boolean	No	true	Allow printing
allow_copy	boolean	No	false	Allow copying text

Returns:

{
  "error": false,
  "url": "https://pdf.co/protected.pdf",
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Add password protection to this PDF with owner password 'admin123' and prevent copying: https://example.com/document.pdf"

Security Best Practice: Never hardcode passwords in conversations. Use this tool through programmatic workflows where passwords are stored securely.

pdf_unlock

Remove password protection from PDF documents (requires correct password).Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL or base64 encoded PDF
password	string	Yes	-	PDF password to unlock

Returns:

{
  "error": false,
  "url": "https://pdf.co/unlocked.pdf",
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Remove password protection from this PDF using password 'secret123': https://example.com/protected.pdf"

PDF Information

pdf_info

Get comprehensive metadata about a PDF document including pages, dimensions, encryption status, and file properties.Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL or base64 encoded PDF

Returns:

{
  "error": false,
  "info": {
    "PageCount": 10,
    "PageRectangle": {
      "Width": 612.0,
      "Height": 792.0
    },
    "Encrypted": false,
    "Title": "Sample Document",
    "Author": "John Doe",
    "Subject": "Report",
    "FileSize": 1024576
  },
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Get metadata for this PDF: https://example.com/document.pdf"

Document Creation Tools

html_to_pdf

Convert HTML content or URLs to PDF with customizable page settings.Parameters:

Parameter	Type	Required	Default	Description
html	string	Yes	-	HTML content or URL
name	string	No	”document.pdf”	Output filename
margins	string	No	null	Margins in format “top,right,bottom,left” (e.g., “10mm,10mm,10mm,10mm”)
orientation	string	No	”Portrait”	Page orientation: “Portrait” or “Landscape”
page_size	string	No	”Letter”	Page size: “Letter”, “A4”, “Legal”, etc.

Returns:

{
  "error": false,
  "url": "https://pdf.co/document.pdf",
  "pageCount": 3,
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Convert this HTML to PDF with A4 page size: <h1>Report</h1><p>Content here...</p>"

url_to_pdf

Convert web pages to PDF documents with automatic rendering.Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	Web page URL
name	string	No	”webpage.pdf”	Output filename
orientation	string	No	”Portrait”	Page orientation: “Portrait” or “Landscape”
page_size	string	No	”Letter”	Page size: “Letter”, “A4”, “Legal”, etc.

Returns:

{
  "error": false,
  "url": "https://pdf.co/webpage.pdf",
  "pageCount": 5,
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Convert this webpage to PDF: https://example.com/article"

image_to_pdf

Convert one or multiple images to a PDF document.Parameters:

Parameter	Type	Required	Default	Description
images	array[string]	Yes	-	List of image URLs or base64 encoded images
name	string	No	”images.pdf”	Output filename

Returns:

{
  "error": false,
  "url": "https://pdf.co/images.pdf",
  "pageCount": 3,
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Convert these images to PDF: https://example.com/img1.jpg, https://example.com/img2.jpg"

Barcode Tools

barcode_generate

Generate QR codes and various barcode formats as PNG, JPG, or SVG images.Parameters:

Parameter	Type	Required	Default	Description
value	string	Yes	-	Barcode value/text to encode
barcode_type	string	No	”QRCode”	Type: “QRCode”, “Code128”, “Code39”, “EAN13”, “EAN8”, “UPCA”, “UPCE”
format	string	No	”png”	Output format: “png”, “jpg”, “svg”

Returns:

{
  "error": false,
  "url": "https://pdf.co/barcode.png",
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Generate a QR code for this URL: https://example.com"

barcode_read

Read and decode barcodes from images with support for multiple barcode types.Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	Image URL or base64 encoded image
barcode_types	array[string]	No	All common types	List of barcode types to detect

Returns:

{
  "error": false,
  "barcodes": [
    {
      "type": "QRCode",
      "value": "https://example.com",
      "confidence": 0.99,
      "x": 100,
      "y": 150,
      "width": 200,
      "height": 200
    }
  ],
  "message": null
}

Credit Cost: 1 credit per requestExample Usage:

"Read barcodes from this image: https://example.com/barcode.jpg"

OCR Tools

ocr_pdf

Perform OCR (Optical Character Recognition) on scanned PDFs to make them searchable.Parameters:

Parameter	Type	Required	Default	Description
url	string	Yes	-	URL or base64 encoded PDF
pages	string	No	All pages	Page range to OCR
lang	string	No	”eng”	Language code: “eng”, “spa”, “fra”, “deu”, “chi”, etc.

Returns:

{
  "error": false,
  "url": "https://pdf.co/ocr.pdf",
  "text": "Extracted text from scanned document...",
  "pageCount": 10,
  "message": null
}

Credit Cost: 3 credits per request (OCR is more resource-intensive)Example Usage:

"OCR this scanned document in English: https://example.com/scanned.pdf"

Authentication & Configuration

API Key Setup

PDF.co requires an API key for all operations. The service uses a credit-based system where operations consume credits from your monthly quota.

Create Account

Visit PDF.co Dashboard and sign up:

No credit card required for free tier
Email verification needed
Instant API key generation

Get API Key

After signup:

Log in to PDF.co Dashboard
Your API key is displayed prominently on the dashboard
Click “Copy” to copy your key
Keep it secure - treat it like a password

Add to Studio

Configure in NimbleBrain Studio:

Navigate to MCP Servers → PDF.co
Click Enable
Paste your API key in the configuration field
Click Save

The server will automatically validate your key and show “Active” status.

Credit-Based Pricing

PDF.co operates on a credit system where each operation consumes credits. Most operations cost 1 credit, with OCR costing 3 credits.

Free Tier
Starter ($9/month)
Professional ($49/month)
Business ($199/month)
Enterprise (Custom)

300 Credits/Month - Perfect for testing and light usageWhat’s Included:

300 operations/month (most tools)
100 OCR operations/month
10 requests per minute
50MB maximum file size
All 18 tools available
24-hour file storage

Best For:

Testing the service
Personal projects
Light document processing
Prototyping workflows

Limitations:

Cannot be used for production at scale
Rate limited to 10 req/min
Files auto-deleted after 24 hours

Credit Consumption

Understanding credit usage helps you plan your monthly budget:

Tool Category	Operation	Credit Cost	Free Tier Usage
Conversion	pdf_to_text	1 credit	300 operations
Conversion	pdf_to_json	1 credit	300 operations
Conversion	pdf_to_html	1 credit	300 operations
Conversion	pdf_to_csv	1 credit	300 operations
Manipulation	pdf_merge	1 credit	300 operations
Manipulation	pdf_split	1 credit	300 operations
Manipulation	pdf_rotate	1 credit	300 operations
Manipulation	pdf_compress	1 credit	300 operations
Manipulation	pdf_add_watermark	1 credit	300 operations
Security	pdf_protect	1 credit	300 operations
Security	pdf_unlock	1 credit	300 operations
Information	pdf_info	1 credit	300 operations
Creation	html_to_pdf	1 credit	300 operations
Creation	url_to_pdf	1 credit	300 operations
Creation	image_to_pdf	1 credit	300 operations
Barcodes	barcode_generate	1 credit	300 operations
Barcodes	barcode_read	1 credit	300 operations
OCR	ocr_pdf	3 credits	100 operations

Cost Optimization: OCR operations cost 3x more than other tools. For scanned documents, consider if you need full OCR or if pdf_to_text (for native PDFs) would suffice.

Rate Limits

API rate limits vary by plan tier:

Plan	Requests/Minute	Burst Limit	File Size	File Retention
Free	10	20	50 MB	24 hours
Starter	30	60	100 MB	7 days
Professional	60	120	200 MB	30 days
Business	120	240	500 MB	90 days
Enterprise	Custom	Custom	Custom	Custom

Rate Limit Handling: If you exceed your rate limit, requests will return HTTP 429 errors. Studio will automatically retry with exponential backoff.

Security Best Practices

API Key Security

Protect Your API Key:

Never commit API keys to version control
Don’t share keys in chat logs or screenshots
Rotate keys regularly (every 90 days)
Use separate keys for development and production
Monitor usage for unauthorized activity

In Studio: API keys are encrypted and stored securely in your local configuration.

Data Privacy

File Handling:

All files are transmitted over HTTPS
Files are automatically deleted after retention period
No files are used for training or analytics
GDPR compliant data processing
SOC 2 Type II certified

Recommendation: For sensitive documents, use the shortest retention period for your tier.

Password Protection

When Using PDF Security Tools:

Never hardcode passwords in Studio conversations
Use strong, unique passwords for protected PDFs
Store passwords in secure password managers
Implement password rotation for long-term protected files
Consider using owner/user password combinations

Example Workflows

Real-world scenarios showing how to use PDF.co tools in NimbleBrain Studio.

Invoice Processing
Contract Generation
Document Archival
Receipt Scanning
Report Distribution
QR Code Campaign
Form Extraction
Document Redaction
Multi-Language OCR
Presentation Archival
Barcode Inventory
Legal Document Prep

Business Value: Automate invoice data extraction from PDF invoicesScenario: Extract structured data from vendor invoices for accountingSteps:

Extract text: “Extract text from this invoice PDF: [invoice-url]”
Parse data: “Extract the invoice number, date, total amount, and vendor name from this text”
Validate: “Check if all required fields are present”

Tools Used: pdf_to_text, pdf_to_jsonCredit Cost: 2 credits per invoiceTime Saved: 5 minutes manual work → 30 seconds automatedExample Prompt:

"Extract invoice data from this PDF and tell me the invoice number, date, total, and vendor: https://example.com/invoice-2025-001.pdf"

Troubleshooting

API Key Invalid

Symptom: Error message “Unauthorized” or “Invalid API key”Solutions:

Verify you copied the complete API key from the dashboard
Check for extra spaces before/after the key
Log in to PDF.co Dashboard and confirm the key
Generate a new API key if needed
In Studio, disable and re-enable PDF.co with the new key

Common Causes:

Partial key copied
Key regenerated but not updated in Studio
Account suspended for non-payment

Credit Limit Exceeded

Symptom: Error message “Insufficient credits” or “Monthly quota exceeded”Solutions:

Check your current credit balance at PDF.co Dashboard
Wait for monthly reset (1st of each month)
Upgrade to a higher tier plan
Purchase additional credit packs

Prevention:

Monitor usage dashboard regularly
Set up usage alerts in your account
Implement credit budgeting in workflows
Consider upgrading before hitting limits

Rate Limit Errors

Symptom: Error message “Too many requests” or HTTP 429 errorsSolutions:

Reduce request frequency
Implement delays between operations (1-2 seconds)
Studio will automatically retry with backoff
Upgrade plan for higher rate limits

Rate Limits by Tier:

Free: 10 requests/minute
Starter: 30 requests/minute
Professional: 60 requests/minute
Business: 120 requests/minute

File Too Large

Symptom: Error message “File size exceeds limit”Solutions:

Compress PDF before uploading
Split large PDF into smaller chunks
Reduce image quality for image-to-PDF conversions
Upgrade plan for larger file limits

File Size Limits:

Free: 50 MB
Starter: 100 MB
Professional: 200 MB
Business: 500 MB
Enterprise: Custom

OCR Quality Issues

Symptom: Extracted text is garbled or incorrectSolutions:

Ensure scanned document has sufficient resolution (300 DPI minimum)
Specify correct language code (lang parameter)
Pre-process images to improve contrast
Rotate images to correct orientation before OCR
Try scanning again with better lighting

Best Practices:

Use 300 DPI or higher resolution
Ensure good lighting and contrast
Avoid shadows and glare
Straighten skewed documents
Specify language for better accuracy

PDF Generation Timeout

Symptom: Operation times out or returns incomplete resultsSolutions:

Use async_mode: true for large files
Split operations into smaller chunks
Reduce page count (use page range parameters)
Check file URL accessibility (must be publicly accessible)
Try again during off-peak hours

When to Use Async Mode:

PDFs with 50+ pages
Large merge operations (5+ files)
OCR operations on multi-page documents
Files larger than 10 MB

Watermark Not Visible

Symptom: Watermark added but not visible in PDFSolutions:

Adjust opacity (try 0.3-0.7 range)
Change watermark color for better contrast
Increase font size
Adjust x/y position coordinates
Verify page range includes desired pages

Position Guidelines:

Most PDFs use 612x792 points (Letter size)
Center position: x=306, y=396
Try different positions to find optimal placement
Use lighter colors (higher opacity) for visibility

Merge Failed

Symptom: PDF merge operation fails or produces corrupted outputSolutions:

Verify all PDF URLs are accessible
Check that all files are valid PDFs
Try merging fewer files at once (batch in groups of 5)
Unlock password-protected PDFs before merging
Use async_mode for large merge operations

Common Issues:

One or more source PDFs corrupted
Protected/encrypted PDFs in the list
Network issues downloading source files
Total merged size exceeds file limit

Tools Not Triggering

Symptom: Studio doesn’t use PDF.co tools when expectedSolutions:

Be more explicit: mention “PDF.co” or specific tool names
Verify server shows “Active” status in Studio
Check API key is correctly configured
Provide file URLs directly (don’t ask Studio to find them)
Use clear action verbs: “extract”, “convert”, “merge”, etc.

Example Good Prompts:

✅ “Extract text from this PDF: [url]”
✅ “Merge these two PDFs: [url1], [url2]”
✅ “Generate a QR code for: [url]”

Example Ambiguous Prompts:

❌ “What’s in this document?” (might not trigger pdf_to_text)
❌ “Can you help with a PDF?” (no action specified)

Links & Resources

Getting Started

PDF.co Dashboard - Manage API keys and monitor usage
API Documentation - Complete API reference
Pricing Plans - Compare plans and upgrade
Support Portal - Help center and FAQs

Tool-Specific Documentation

PDF Conversion APIs - Text, JSON, HTML, CSV extraction
PDF Manipulation - Merge, split, rotate, compress
Document Generation - HTML to PDF, URL to PDF
OCR API - Optical character recognition
Barcode API - Generate and read barcodes

Support

Status Page - Service uptime and incidents
Email Support - Technical support
Community Forum - User discussions
GitHub Examples - Code samples

Learning Resources

PDF.co vs Other Services

How PDF.co Compares:Advantages:

✅ Simple credit-based pricing (no per-page fees)
✅ Comprehensive API (18 tools in one service)
✅ FastMCP integration for Studio
✅ Generous free tier (300 credits/month)
✅ No watermarks on free tier
✅ 24-hour file retention (not immediate deletion)

Alternatives:

Adobe PDF Services: More expensive, enterprise-focused
iLovePDF: Limited API, consumer-focused
Smallpdf: No free API tier
PyPDF2/pdfplumber: Self-hosted but limited features

Best For: Teams wanting all-in-one PDF processing without managing multiple services.

Credit Usage Optimization

Maximize Your Free Tier:1. Batch Operations (1 credit for multiple items):

Use pdf_merge for multiple PDFs (1 credit total)
Use image_to_pdf for multiple images (1 credit total)
Use barcode_read on images with multiple codes (1 credit total)

2. Avoid OCR When Possible (3 credits):

Try pdf_to_text first (native PDFs don’t need OCR)
Use ocr_pdf only for scanned/image-based PDFs
Specify page ranges to OCR only needed pages

3. Compress Smart:

Use compression before other operations
Balance quality vs file size (start with “balanced”)
Compress before merging to save processing time

4. Use Page Ranges:

Extract only needed pages: pages="1-5"
Skip blank pages to reduce processing
Test on single pages before full document

Understanding Tool Categories

How Tools Are Organized:Conversion Tools (Extract Data):

Input: Existing PDF
Output: Text, JSON, HTML, CSV
Use when: You need to read/analyze PDF content

Manipulation Tools (Modify PDFs):

Input: Existing PDF(s)
Output: Modified PDF
Use when: You need to change PDF structure

Security Tools (Protect Content):

Input: Existing PDF
Output: Protected/unlocked PDF
Use when: You need access control

Creation Tools (Generate PDFs):

Input: HTML, URL, or images
Output: New PDF
Use when: You need to create PDFs from scratch

Barcode Tools (QR & Barcodes):

Input: Text (generate) or Image (read)
Output: Barcode image or decoded data
Use when: Product tracking, marketing, inventory

OCR Tools (Text Recognition):

Input: Scanned PDF or images
Output: Searchable PDF + text
Use when: Paper documents need digitization

File URL Requirements

How to Provide Files to PDF.co:Option 1: Public URLs (Recommended):

File must be publicly accessible
No authentication required
HTTPS preferred (HTTP works)
Examples: S3 public URLs, Dropbox public links, web hosting

Option 2: Base64 Encoding:

For files you can’t make public
Encode file as base64 string
Include data URI prefix: data:application/pdf;base64,
More complex but works for private files

Studio Limitation:

Studio cannot directly upload files from your computer
Must provide URL or base64-encoded string
For local files: upload to cloud storage first, then use URL

Best Practice:

Use cloud storage (S3, Dropbox, Google Drive)
Generate temporary public URLs (expiring links)
Remove files after processing to maintain privacy

Async vs Sync Operations

When to Use Async Mode:Synchronous (Default):

Studio waits for immediate response
Best for: Fast operations, small files, single pages
Timeout: 60 seconds
Most operations complete instantly

Asynchronous (async_mode: true):

PDF.co processes in background
Returns job ID, you poll for completion
Best for: Large files, many pages, OCR, large merges
No timeout limit

When to Enable Async:

PDFs with 50+ pages
Files larger than 25 MB
Merging 10+ documents
OCR on multi-page documents
Operations taking longer than 30 seconds

Studio Handling:

Studio automatically handles async operations
You’ll see “Processing…” status
Results appear when ready
No manual polling needed

Error Code Reference

Common PDF.co Error Codes:401 Unauthorized:

Invalid or missing API key
Solution: Check API key in Studio configuration

402 Payment Required:

Credits exhausted
Solution: Wait for monthly reset or upgrade plan

429 Too Many Requests:

Rate limit exceeded
Solution: Slow down requests or upgrade plan

400 Bad Request:

Invalid parameters (wrong URL, bad page range)
Solution: Check tool documentation for correct format

413 Payload Too Large:

File exceeds size limit
Solution: Compress file or upgrade plan

500 Internal Server Error:

PDF.co service issue
Solution: Check Status Page, retry later

503 Service Unavailable:

Temporary outage
Solution: Wait 5 minutes and retry

Studio will show user-friendly error messages for all these codes.

Best Practices for Production

Production Deployment Guidelines:1. API Key Management:

Use separate keys for dev/staging/production
Rotate keys quarterly
Never log or expose keys
Monitor usage for anomalies

2. Error Handling:

Implement retry logic with exponential backoff
Handle rate limits gracefully (queue requests)
Validate file URLs before API calls
Log errors for debugging (exclude sensitive data)

3. Cost Control:

Monitor credit usage daily
Set up alerts at 80% quota
Implement usage caps per user/workflow
Review credit consumption monthly

4. Performance:

Use async mode for large operations
Cache results when appropriate
Compress files before processing
Use page ranges to process only needed content

5. Security:

Delete files immediately after processing
Use shortest retention period for your tier
Encrypt sensitive PDFs with pdf_protect
Validate file types before processing

6. Reliability:

Have fallback for service outages
Test with sample files regularly
Monitor PDF.co status page
Keep Studio MCP connection active

Ready to Process Documents? Enable PDF.co in NimbleBrain Studio and start with the free tier. Most operations cost just 1 credit, and you get 300 credits per month to explore all 18 tools!

Get Started

Core Features

Developer Tools

Overview

What it does

Use Cases

Quick Start

Available Tools

PDF Conversion Tools

PDF Manipulation Tools

PDF Security Tools

PDF Information

Document Creation Tools

Barcode Tools

OCR Tools

Authentication & Configuration

API Key Setup

Credit-Based Pricing

Credit Consumption

Rate Limits

Security Best Practices

Example Workflows

Troubleshooting

Links & Resources

Getting Started

Tool-Specific Documentation

Support

Learning Resources

Get Started

Core Features

Developer Tools

​Overview

What it does

Use Cases

​Quick Start

​Available Tools

​PDF Conversion Tools

​PDF Manipulation Tools

​PDF Security Tools

​PDF Information

​Document Creation Tools

​Barcode Tools

​OCR Tools

​Authentication & Configuration

​API Key Setup

​Credit-Based Pricing

​Credit Consumption

​Rate Limits

​Security Best Practices

​Example Workflows

​Troubleshooting

​Links & Resources

​Getting Started

​Tool-Specific Documentation

​Support

​Learning Resources

Overview

Quick Start

Available Tools

PDF Conversion Tools

PDF Manipulation Tools

PDF Security Tools

PDF Information

Document Creation Tools

Barcode Tools

OCR Tools

Authentication & Configuration

API Key Setup

Credit-Based Pricing

Credit Consumption

Rate Limits

Security Best Practices

Example Workflows

Troubleshooting

Links & Resources

Getting Started

Tool-Specific Documentation

Support

Learning Resources