Open a PDF

API docs preview

Build PDF workflows with signed uploads and jobs.

These docs are rendered from the backend developer contract route. They expose current endpoint contracts, job metadata, idempotency guidance, webhook events, and local launch boundaries without duplicating the API surface in page-local arrays.

Open playgroundWhite-label tools

Authentication

Send API keys as bearer tokens from a server process. The backend contract marks browser execution as disabled.

Idempotency

Pass `idempotency-key` on mutation endpoints. Repeated requests with the same key must return the original mutation result instead of duplicating work.

Launch state

Not Live; local contract evidence only

Endpoint contracts

POST/v1/uploads/signed-urlCreate a short-lived direct upload URL for a source file.
POST/v1/uploads/{uploadId}/completeConfirm uploaded file metadata before processing.
POST/v1/jobsStart an async PDF, OCR, conversion, extraction, or AI job.
GET/v1/jobs/{jobId}Read status, progress, expiry, and failure details.
POST/v1/jobs/{jobId}/cancelCancel a queued or running job.
GET/v1/jobs/{jobId}/resultRequest a signed result URL after the job succeeds.
GET/v1/billing/catalogRead server-owned billing catalog and API pricing metadata.
GET/v1/api-keysList stored API-key metadata without returning secret material.
POST/v1/webhooksRegister an endpoint URL and subscribed job lifecycle events.
POST/v1/webhooks/sign-testGenerate signed test headers for local webhook verification.
POST/v1/webhooks/deliveries/{deliveryId}/replayReset a replay-window-valid dead-lettered webhook delivery for worker redelivery.
curl https://api.clearpdf.net/v1/jobs \
  -H "authorization: Bearer $CLEARPDF_API_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: example-invoice-001" \
  -d '{
    "jobType": "extract_invoice",
    "processingMode": "api",
    "inputFileIds": ["file_example_source"],
    "settings": { "confidenceThreshold": 0.85 },
    "webhookUrl": "https://example.com/webhooks/clearpdf"
  }'

Signed upload and job flow

Upload and job operations use bearer auth, server-side API keys, scoped permissions, and idempotency for mutation retries. Result URLs are requested separately after a job succeeds.

Jobs and polling

Jobs start as queued, report progress from 0 to 100, and finish as succeeded, failed, cancelled, deleted, or expired. The job contract includes worker service, operation, pricing key, and quality checks.

{
  "id": "job_example_queued",
  "jobType": "extract_invoice",
  "processingMode": "api",
  "status": "queued",
  "progress": 0,
  "inputFileIds": [
    "file_example_source"
  ],
  "apiContract": {
    "family": "document_extraction_api",
    "endpoint": "jobs.create",
    "endpointPricingKey": "document.extract",
    "requestSchema": "create_job_request_v1",
    "responseSchema": "job_response_v1",
    "settingsSchema": "structured_extraction_settings_v1",
    "workerService": "api-orchestrator",
    "workerOperation": "extract-invoice",
    "outputKind": "json",
    "outputContainer": "single_file",
    "workerContractVersion": "api_orchestrator_contract_v1",
    "qualityControls": [
      "queue_receipt_contract"
    ],
    "workerAdmission": {
      "requiresWorkerHeartbeat": true,
      "requiresQueueDispatch": true,
      "workerServiceUrlEnvVar": "AI_WORKER_URL",
      "requiresCloudObjectStorage": true,
      "resultMaterializationVerificationRequiredInProduction": true,
      "requiredReadiness": [
        "worker_active",
        "worker_contract_version",
        "worker_lease_fresh",
        "operation_ready",
        "capacity_available",
        "queue_subscription",
        "storage_read",
        "storage_write",
        "malware_admission",
        "result_write",
        "queue_backend_bullmq",
        "worker_service_url",
        "cloud_object_storage",
        "reserved_output_uri_materialized"
      ],
      "requiredRuntimeBinaries": [],
      "requiredOutputProofs": [
        "contentType",
        "sizeBytes",
        "magicBytes",
        "reservedOutputUri"
      ],
      "productionLaunchStatus": "not_live"
    },
    "webhookEvents": [
      "job.created",
      "job.progress",
      "job.succeeded",
      "job.failed",
      "job.cancelled"
    ],
    "idempotencyKey": "example-invoice-001",
    "webhookConfigured": true,
    "localContractOnly": true,
    "productionLaunchStatus": "not_live"
  }
}

OCR and extraction jobs

Ocr Pdfocr_pdfocr_job_settings_v1
Searchable Pdfsearchable_pdfocr_job_settings_v1
Html To Pdfhtml_to_pdfhtml_to_pdf_settings_v1
Extract Textextract_texttext_extraction_settings_v1
Extract Invoiceextract_invoicestructured_extraction_settings_v1
Extract Tableextract_tablestructured_extraction_settings_v1
import os
import requests

response = requests.post(
    "https://api.clearpdf.net/v1/jobs",
    headers={
        "authorization": f"Bearer {os.environ['CLEARPDF_API_KEY']}",
        "content-type": "application/json",
        "idempotency-key": "example-python-001",
    },
    json={
        "jobType": "ocr_pdf",
        "processingMode": "api",
        "inputFileIds": ["file_example_source"],
        "settings": {"languages": ["eng"], "deskew": True},
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["status"])

Python REST sample

The generated sample uses environment-provided API keys, a non-secret example file ID, explicit idempotency, and HTTP error handling before reading the response.

TypeScript auth and errors

import { ClearPDF, ClearPdfApiError } from "@clearpdf/sdk-typescript";

const clearpdf = new ClearPDF({ apiKey: process.env.CLEARPDF_API_KEY });

try {
  const job = await clearpdf.client.jobs.create({
    jobType: "extract_text",
    processingMode: "api",
    inputFileIds: ["file_example_source"],
    settings: { includeLayout: true, includePageCitations: true },
    idempotencyKey: "example-extract-text-001"
  });
  console.log(job.status);
} catch (error) {
  if (error instanceof ClearPdfApiError) {
    console.error({ status: error.status, code: error.code });
  }
  throw error;
}

Python SDK auth and errors

import os

from clearpdf import ClearPDF, ClearPdfApiError

client = ClearPDF(api_key=os.environ["CLEARPDF_API_KEY"])

try:
    job = client.create_text_extraction_job(
        ["file_example_source"],
        settings={"includeLayout": True, "includePageCitations": True},
        idempotency_key="example-extract-text-001",
    )
    print(job["status"])
except ClearPdfApiError as error:
    print({"status": error.status, "code": error.code})
    raise

Webhooks

Subscribe to job.created, job.progress, job.succeeded, job.failed, job.cancelled, file.deleted. Consumers should verify timestamp tolerance and HMAC signature before trusting a job status transition.

const rawBody = await request.text();
const timestamp = request.headers.get("x-clearpdf-timestamp");
const signature = request.headers.get("x-clearpdf-signature");

// Verify HMAC-SHA256 over `${timestamp}.${rawBody}` with your webhook secret.
// Reject missing headers and timestamps outside the configured tolerance.

Generated from

apps/api/src/schemas/jobs.ts#createJobSchema, apps/api/src/services/jobs.ts#apiContractForJob, apps/api/src/app.ts#/v1/developer

Errors

400 BAD_REQUEST, 401 UNAUTHORIZED, 403 FORBIDDEN, 409 CONFLICT, 429 RATE_LIMITED

Evidence boundary

Current API documentation is backend-generated local contract evidence. It does not prove production traffic, partner approval, live payment processing, or webhook deliverability SLA.