PDF OCR Service

Cobbling AI's PDF OCR service delivers fast processing, high accuracy, and rich structured outputs for PDF documents.

Key Benefits

• Enhanced recognition quality for complex layouts, tables, and mathematical notation
• Faster turnaround times for large documents through an optimized processing pipeline
• Real-time webhook support to keep your applications up to date

Features

• High-accuracy OCR processing using advanced AI models
• Automatic conversion of:
  • Mathematical equations to LaTeX format
  • Tables to Markdown format
• Smart handling of:
  • Headers and footers
  • References and footnotes
  • Natural handwriting

Subscription & Pricing

PDF OCR is available through Cobbling AI subscriptions. To get started:

1. Sign up for a subscription on the Cobbling AI website
2. Generate an API key in the account dashboard
3. Use the API key to authenticate requests to the PDF OCR service

Generating Your API Key

After subscribing to the service:

1. Log in to your Cobbling AI account
2. Create a project from your dashboard
3. Navigate to your project and click "Create new secret key"
4. Copy and securely store your API key
5. Use this key in your API requests

API Usage

The PDF OCR service uses an asynchronous workflow: upload a PDF, then poll for status (or subscribe to a webhook).

There are two upload endpoints. Most clients should use Option A — it's a single request and works well up to 100 MB.

Step 1: Upload PDF File

Option A: Single-Request Upload (Recommended)

Send the PDF directly as a multipart/form-data body in one request. This is the simplest path: no presigning, no secondary PUT. The response returns the job ID you'll use to check status.

POST https://api.commapdf.cobbling.ai/v1/parsing/upload
Authorization: Bearer <your_api_key>
Content-Type: multipart/form-data

file: <pdf_file_binary>

Response (201)

{
  "id": 28591,
  "status": "pending"
}

The id is your job ID. Use it with the Job Status endpoint or with Fetching Results after a webhook fires.

Limits

• Maximum file size: 50 MB (the worker buffers the body in memory; for larger files use Option B)

Option B: Presigned URL Upload (Advanced / Large Files)

For files larger than 50 MB, or for browser clients that want to skip a worker hop, request a presigned URL first and PUT the PDF directly to storage. The client uploads to R2 directly, so worker memory is not the bottleneck.

1. Get the presigned URL

POST https://api.pdf-ocr.cobbling.ai/v1/upload/direct
Authorization: Bearer <your_api_key>
Content-Type: application/json

{
  "fileName": "document.pdf",
  "fileType": "application/pdf"
}

Request fields:

• fileName (string, required): Name of the PDF file to upload (max 255 characters)
• fileType (string, required): MIME type of the file — use application/pdf

Response (201):

{
  "jobGuid": "unique_job_identifier",
  "url": "presigned_upload_url",
  "key": "upload_key"
}

2. Upload the PDF to the presigned URL

PUT <presigned_upload_url>
Content-Type: application/pdf

<pdf_file_binary>

The presigned URL is valid for one hour. Once the PUT succeeds, the pipeline picks up the upload automatically.

Supported File Formats

• PDF (one or more pages)

Step 2: Check Processing Status

Poll this endpoint to track progress. When status === "complete", the response includes the extracted markdown for each page.

GET https://api.pdf-ocr.cobbling.ai/v1/workflows/:instanceId/status
Authorization: Bearer <your_api_key>

:instanceId is the jobGuid from Option B, or the guid of the job you got back from Option A (retrieve it with GET /v1/parsing/jobs/:id if needed — see below).

Response (200)

{
  "instanceId": "e8e44b74-a155-4458-b90f-e90fd836e15a",
  "status": "complete",
  "error": null,
  "output": {
    "totalPages": 78,
    "processedPages": 78,
    "status": "completed",
    "error": null,
    "createdAt": "2026-05-01T08:51:52.576Z",
    "updatedAt": "2026-05-01T08:54:03.242Z",
    "markdownFiles": [
      { "pageNumber": 1, "markdown": "# Document Title\n\nExtracted text from page 1..." },
      { "pageNumber": 2, "markdown": "## Section Header\n\nExtracted text from page 2..." }
    ]
  }
}

Status Values

• queued – Workflow is queued for processing
• running – Workflow is currently being processed
• paused – Workflow execution is paused
• errored – Workflow encountered an error (see error field)
• terminated – Workflow was terminated
• complete – Workflow completed successfully
• waiting – Workflow is waiting on an event
• waitingForPause – Workflow is finishing the current step before pausing
• unknown – Status could not be determined

Error Responses

400 – Bad Request

{ "code": 400, "message": "Invalid instance ID or workflow not found" }

401 – Unauthorized

{ "code": 401, "message": "Invalid or missing bearer token" }

404 – Workflow Instance Not Found

{ "code": 404, "message": "Workflow instance not found" }

500 – Internal Server Error

{ "code": 500, "message": "Internal server error" }

Webhook Integration

Use webhooks to receive automatic notifications when a PDF OCR job changes state — instead of polling.

Go to the dashboard to create, edit, and delete webhooks.

How to Add an Endpoint

To start listening, configure your endpoints. Adding an endpoint is as simple as providing a URL you control and selecting the event types you want to listen to. If you don't specify any event types, your endpoint will receive all events by default. This is helpful for getting started, but we recommend narrowing this once you know which events you care about. If your endpoint isn't ready yet, click "with Svix Play" to generate a temporary URL where you can inspect events.

How to Test Endpoints

After adding an endpoint, the "Testing" tab lets you send test events. You can click into a delivery to inspect the payload, all attempts, and final delivery status.

Signature Verification

For information on how to verify webhook signatures, see How to Verify Webhooks with the Svix Libraries.

Fetching Results

After receiving a webhook, use the job_id from the payload to fetch the markdown directly:

GET https://api.commapdf.cobbling.ai/v1/parsing/jobs/:id/result/markdown
Authorization: Bearer <your_api_key>

Response (200):

{ "markdown": "# Document Title\n\n..." }

:id is the numeric job ID from the webhook payload.

Example: End-to-End

# 1. Upload (single request)
curl -X POST "https://api.commapdf.cobbling.ai/v1/parsing/upload" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@document.pdf"
# → {"id": 28591, "status": "pending"}

# 2. Once the webhook fires (or just poll), fetch the markdown
curl "https://api.commapdf.cobbling.ai/v1/parsing/jobs/28591/result/markdown" \
  -H "Authorization: Bearer $API_KEY"
# → {"markdown": "# Document Title\n\n..."}

Security

• API key authentication required for all requests
• Maximum file size: 50 MB (Option A) / 5 GB (Option B presigned URL)
• API key revocation available in your account settings
• Usage tracking available in your dashboard