API Documentation

Authentication

All API requests require authentication using an API key. Include your key in theX-API-Key header with every request.

X-API-Key: sk_live_your_api_key_here

Include your API key in the X-API-Key header with every request.

Base URL

https://fileconvertlab.com/api/v1

Create Conversion Job

Submit a file for conversion. The API uses an asynchronous job-based workflow.

Request

Content-Type: multipart/form-data

Response (202 Accepted)

{
  "id": "job_abc123xyz",
  "status": "processing",
  "operation": "pdf-to-word",
  "created_at": "2025-12-07T10:30:00Z",
  "estimated_seconds": 15,
  "file": {
    "name": "document.pdf",
    "size": 1048576,
    "mime_type": "application/pdf"
  }
}

Get Job Status

Check the status of a conversion job. Poll this endpoint until status iscompleted,failed orrejected.

Response

{
  "id": "job_abc123xyz",
  "status": "completed",
  "operation": "pdf-to-word",
  "progress": 100,
  "created_at": "2025-12-07T10:30:00Z",
  "completed_at": "2025-12-07T10:30:12Z",
  "result": {
    "download_url": "/v1/jobs/job_abc123xyz/download",
    "expires_at": "2025-12-07T11:30:12Z",
    "file_name": "document.docx",
    "file_size": 524288
  }
}

Status Values

Download Result

Download the converted file. Only available after job status iscompleted.

Returns the binary file with appropriate Content-Type and Content-Disposition headers.

Supported Operations

PDF Conversions

Office to PDF

OCR Operations

ocr-*-to-text is accepted as an alias of ocr-*-to-txt. GIF analysis (POST /api/v1/gif/analyze) and PDF editing (POST /api/v1/pdf/apply-ops) are separate endpoints, not job operations.

OCR Languages

Values for the language option (auto picks the script from the page):

PDF Utilities

Webhooks

Pass webhook_url when you create a job and we POST a JSON body to it once the job reaches a terminal state. The events arejob.completed,job.failed andjob.rejected. The URL must be public: private, loopback and link-local addresses are refused.

Payload

{
  "event": "job.completed",
  "job_id": "job_abc123xyz",
  "status": "completed",
  "operation": "pdf-to-word",
  "result": {
    "download_url": "https://fileconvertlab.com/api/v1/jobs/job_abc123xyz/download",
    "file_name": "report_20260925_101500.docx",
    "file_size": 51234,
    "expires_at": "2026-09-25T11:15:00Z"
  }
}

Downloading the result still needs your API key, so treatdownload_url as a URL to call with theX-API-Key header, not a public link.

Retries

A delivery counts as successful on any 2xx response. Anything else, including a timeout after 30 seconds, is retried: three attempts in total, the second about 5 seconds later and the third about 30 seconds after that. Every request carriesX-FCL-Delivery-Attempt with the attempt number, so a receiver can tell a retry from a first delivery.

Signed payloads

Send webhook_secret together with the webhook URL and every delivery arrives with anX-FCL-Signature header. The header holds the Unix timestamp of the delivery and an HMAC-SHA256 digest of<timestamp>.<raw body> keyed with your secret, hex encoded: t=1800000000,v1=5f2b…

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(','))
    timestamp, digest = parts['t'], parts['v1']
    if abs(time.time() - int(timestamp)) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, digest)

Compare digests in constant time, reject deliveries whose timestamp is far from now, and verify against the raw request body rather than a re-serialised copy of the JSON.

Rate Limits

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 50

X-RateLimit-Remaining: 45

X-RateLimit-Reset: 1701962400

Error Handling

Error Response Format

{
  "error": {
    "code": "INVALID_FILE_TYPE",
    "message": "Expected PDF file, got image/png",
    "details": {
      "expected": ["application/pdf"],
      "received": "image/png"
    }
  }
}

Error Codes

Code Examples

cURL

 Create conversion job

curl -X POST https://fileconvertlab.com/api/v1/jobs \

  -H "X-API-Key: sk_live_abc123" \

  -F "file=@document.pdf" \

  -F "operation=pdf-to-word"

 Check job status

curl https://fileconvertlab.com/api/v1/jobs/job_abc123 \

  -H "X-API-Key: sk_live_abc123"

 Download result

curl -O https://fileconvertlab.com/api/v1/jobs/job_abc123/download \

  -H "X-API-Key: sk_live_abc123"

JavaScript

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('operation', 'pdf-to-word');

// Create job
const response = await fetch('https://fileconvertlab.com/api/v1/jobs', {
  method: 'POST',
  headers: { 'X-API-Key': 'sk_live_abc123' },
  body: formData
});
let job = await response.json();

// Poll until complete
while (job.status === 'processing') {
  await new Promise(r => setTimeout(r, 1000));
  const res = await fetch(`https://fileconvertlab.com/api/v1/jobs/${job.id}`, {
    headers: { 'X-API-Key': 'sk_live_abc123' }
  });
  job = await res.json();
}

// Download result
if (job.status === 'completed') {
  window.location.href =
    `https://fileconvertlab.com${job.result.download_url}`;
}

Python

import requests
import time

API_KEY = 'sk_live_abc123'
BASE_URL = 'https://fileconvertlab.com/api/v1'
headers = {'X-API-Key': API_KEY}

# Create job
with open('document.pdf', 'rb') as f:
    response = requests.post(
        f'{BASE_URL}/jobs',
        headers=headers,
        files={'file': f},
        data={'operation': 'pdf-to-word'}
    )
job = response.json()

# Poll until complete
while job['status'] == 'processing':
    time.sleep(1)
    response = requests.get(
        f"{BASE_URL}/jobs/{job['id']}",
        headers=headers
    )
    job = response.json()

# Download result
if job['status'] == 'completed':
    response = requests.get(
        f"{BASE_URL}{job['result']['download_url']}",
        headers=headers
    )
    with open('document.docx', 'wb') as f:
        f.write(response.content)