API playground

Explore the ClearPDF API contract before going live.

The playground is generated from the backend developer contract route. It shows request shapes, idempotency rules, job contract metadata, SDK usage, and webhook verification without accepting live secrets in the browser.

Read API docs White-label tools

API keys

Use `Authorization: Bearer $CLEARPDF_API_KEY` from a server process only. Browser tools must not expose live secret keys.

Required headers

authorization, content-type, idempotency-key

Retries

Repeated requests with the same key must return the original mutation result instead of duplicating work.

Endpoint catalog

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.

Request example

Job creation accepts uploaded file IDs, typed settings, an optional webhook URL, and a client-generated idempotency key. This example comes from `/v1/developer/api-contracts`.

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"
  }'

{
  "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"
  }
}

Response example

Job responses include status, progress, timestamps, and backend contract metadata. Fetch the result endpoint after the job status becomes succeeded.

Webhook testing

Webhook payloads are signed over timestamp and raw body. Reject missing signatures, replayed timestamps, and unexpected events.

{
  "id": "evt_example_job_succeeded",
  "event": "job.succeeded",
  "createdAt": "2026-01-15T00:00:00.000Z",
  "data": {
    "clearPdfJobId": "job_example_queued",
    "status": "succeeded",
    "resultFileId": "file_example_result"
  }
}

Featured job contract

Job typeextract_invoiceDocument Extraction Api

Pricing keydocument.extractstructured_extraction_settings_v1

Workerapi-orchestratorextract-invoice

TypeScript SDK

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

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

const job = await clearpdf.client.jobs.create({
  jobType: "ocr_pdf",
  processingMode: "api",
  inputFileIds: ["file_example_source"],
  settings: { languages: ["eng"], deskew: true },
  idempotencyKey: "example-ocr-001"
});

console.log(job.status);

Python REST sample

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"])

TypeScript auth, idempotency, 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, idempotency, 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

Production boundary

Launch status: Not Live
Evidence: Local Contract
Browser execution: Disabled

This playground reads a backend contract and remains non-mutating in the browser. Live execution still needs account auth, quota checks, audit logs, and secret redaction.

Generated from

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

Error examples

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

Benchmarks

Local benchmark evidence remains published in `docs/compliance/compression-benchmark-results.md` and `docs/compliance/compression-benchmark-results.json`.