Developers/API Reference

API v1.0REST API

FlexiDoc API Documentation

Convert PDFs to semantic HTML with our powerful REST API. Built for developers, trusted by enterprises.

Performance

50ms

Avg response time

Uptime

99.9%

SLA guaranteed

Global

Edge locations

Security

SOC 2

Type II certified

Quick Start

Get Your API Key

Install SDK

Install our official SDK for your preferred programming language.

pip install flexidoc

Make Your First Call

Convert your first PDF in just a few lines of code.

Code Examples

example.py

import flexidoc

client = flexidoc.Client(api_key="your_api_key")

# Convert PDF to HTML
with open("document.pdf", "rb") as f:
    result = client.convert_pdf_to_html(
        file=f,
        options={
            "preserve_formatting": True,
            "extract_images": True,
            "semantic_html": True,
            "ocr_enabled": True,
            "accessibility_check": True
        }
    )
    
print(result.html)
print(f"Conversion ID: {result.conversion_id}")
print(f"Pages processed: {result.metadata['pages']}")

API Endpoints

Endpoints

Convert PDF to HTML

POST/v1/convert/pdf-to-html

Convert PDF documents to clean, semantic HTML with AI-powered accuracy.

Request Parameters

fileFilePDF file to convert

urlStringURL to PDF (alternative to file)

preserve_formattingBooleanMaintain original formatting

extract_imagesBooleanExtract and include images

semantic_htmlBooleanGenerate semantic HTML5

ocr_enabledBooleanEnable OCR for scanned PDFs

accessibility_checkBooleanInclude WCAG compliance check

webhook_urlStringURL for async completion

Response

{
  "conversion_id": "conv_abc123xyz",
  "status": "completed",
  "html": "<article class=\"document\">...</article>",
  "css": ".document { font-family: Arial; }",
  "metadata": {
    "pages": 10,
    "title": "Annual Report 2024",
    "author": "John Doe",
    "subject": "Financial Statement",
    "keywords": ["finance", "annual", "report"],
    "created_at": "2024-01-01T00:00:00Z",
    "modified_at": "2024-01-15T10:30:00Z",
    "producer": "Adobe PDF",
    "language": "en",
    "accessibility_score": 98,
    "word_count": 5420,
    "image_count": 12
  },
  "download_url": "https://cdn.flexidoc.io/results/conv_abc123xyz.zip",
  "expires_at": "2024-01-08T00:00:00Z",
  "processing_time": 2.34
}

Example Request

curl -X POST https://api.flexidoc.io/v1/convert/pdf-to-html \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]" \
  -F "options[preserve_formatting]=true" \
  -F "options[extract_images]=true" \
  -F "options[semantic_html]=true"

Authentication

API Key Authentication

Use Bearer authentication with your API key for all requests.

Authorization: Bearer your_api_key_here

Security Best Practices:

Never expose API keys in client-side code
Use environment variables for key storage
Rotate keys regularly
Use different keys for dev/staging/production

OAuth 2.0 (Enterprise)

Enterprise customers can use OAuth 2.0 for enhanced security.

OAuth 2.0 provides token-based authentication with automatic refresh and fine-grained permissions.

Automatic token refresh

Granular permission scopes

SSO integration support

Webhooks

Async Processing with Webhooks

Receive real-time notifications when conversions complete or fail.

Available Events

conversion.startedConversion began processing

conversion.completedConversion finished successfully

conversion.failedConversion encountered an error

batch.completedAll batch conversions finished

Webhook Payload

{
  "event": "conversion.completed",
  "conversion_id": "conv_abc123",
  "batch_id": null,
  "status": "completed",
  "download_url": "https://cdn.flexidoc.io/...",
  "metadata": {
    "pages": 10,
    "processing_time": 2.34,
    "file_size": 1048576
  },
  "timestamp": "2024-01-01T00:00:00Z",
  "retry_count": 0
}

Webhook Security

Verify webhook signatures to ensure requests come from FlexiDoc.

Signature Verification

All webhooks include a signature header:

X-FlexiDoc-Signature: sha256=...

Verification Example

verify_webhook.py

import hmac
import hashlib

def verify_webhook(payload, signature_header, webhook_secret):
    """
    Verify webhook signature from FlexiDoc
    """
    expected_signature = hmac.new(
        webhook_secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(
        f"sha256={expected_signature}",
        signature_header
    )

# In your webhook handler
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-FlexiDoc-Signature')
    
    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
        return "Unauthorized", 401
    
    event = request.json
    
    if event['event'] == 'conversion.completed':
        # Handle completed conversion
        conversion_id = event['conversion_id']
        download_url = event['download_url']
        # ... process the conversion
    
    return "OK", 200

Official SDKs

Python

Full-featured Python SDK with async support, type hints, and comprehensive documentation.

pip install flexidoc

Node.js

Modern JavaScript SDK with TypeScript support, promises, and streaming capabilities.

npm install flexidoc

PHP

PHP SDK with PSR-4 autoloading, Guzzle HTTP client, and Laravel integration.

composer require flexidoc/sdk

Ruby

Ruby SDK with idiomatic design, Rails integration, and comprehensive test coverage.

gem install flexidoc

Go

Go SDK with context support, error handling, and concurrent processing capabilities.

go get github.com/flexidoc/go-sdk

Java

Java SDK with Spring Boot integration, async support, and Maven/Gradle compatibility.

implementation 'io.flexidoc:sdk:1.0.0'

Error Handling

Error Response Format

All API errors follow a consistent format for easy handling:

{
  "error": {
    "code": "invalid_file_format",
    "message": "The uploaded file is not a valid PDF",
    "details": {
      "file_type": "image/jpeg",
      "expected": "application/pdf"
    },
    "request_id": "req_abc123xyz",
    "documentation_url": "https://docs.flexidoc.io/errors#invalid_file_format"
  }
}

Common Error Codes

400 Bad Request

Invalid request parameters or malformed data

401 Unauthorized

Missing or invalid API key

403 Forbidden

Valid key but insufficient permissions

404 Not Found

Requested resource doesn't exist

429 Too Many Requests

Rate limit exceeded

500 Internal Server Error

Unexpected server error

Retry Strategy

Implement exponential backoff for transient errors:

# Retry with exponential backoff
import time

def retry_request(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except ApiError as e:
            if e.status_code >= 500 or e.status_code == 429:
                if attempt < max_retries - 1:
                    wait_time = 2 ** attempt
                    time.sleep(wait_time)
                    continue
            raise

Rate Limits & Quotas

Rate Limit Headers

Monitor your usage with response headers:

X-RateLimit-Limit - Requests allowed per minute

X-RateLimit-Remaining - Requests remaining

X-RateLimit-Reset - Unix timestamp when limit resets

X-Quota-Remaining - Monthly conversions remaining

Plan	Requests/min	Monthly Conversions	Max File Size	Concurrent Jobs
Free	10	100	10 MB	1
Starter	60	1,000	50 MB	5
Professional	300	10,000	100 MB	20
Enterprise	Custom	Unlimited	Custom	Unlimited

API Changelog

v1.2.0

Released January 15, 2024

Latest

Added OCR support for scanned PDFs
New accessibility_check option for WCAG compliance
Improved batch processing performance by 40%
Added retry_count field to webhook payloads

v1.1.0

Released December 1, 2023

Introduced batch conversion endpoints
Added webhook configuration API
New SDKs for Ruby and Go

v1.0.0

Released October 15, 2023

Initial public release
Core PDF to HTML conversion
Python, Node.js, and PHP SDKs

Need Help?

Our team is here to help you integrate FlexiDoc into your application.