OCR Forge API Documentation

X-API-Key: ofk_your_api_key_here

Authorization: Bearer ofk_your_api_key_here

curl -X POST https://api.ocrforge.co.za/documents \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ofk_your_api_key" \
  -d '{
    "filename": "invoice.pdf",
    "mimeType": "application/pdf",
    "outputFormat": "json"
  }'

{
  "job_id": "doc_a1b2c3d4e5f6",
  "status": "awaiting_upload",
  "upload_url": "https://s3.af-south-1.amazonaws.com/...",
  "upload_expires_in": 900,
  "status_url": "/documents/doc_a1b2c3d4e5f6",
  "instructions": "PUT your file to upload_url..."
}

curl -X PUT "${UPLOAD_URL}" \
  -H "Content-Type: application/pdf" \
  --data-binary @invoice.pdf

# Check status
curl https://api.ocrforge.co.za/documents/doc_a1b2c3d4e5f6 \
  -H "X-API-Key: ofk_your_api_key"

# When status is "completed", get the result
curl https://api.ocrforge.co.za/documents/doc_a1b2c3d4e5f6/result \
  -H "X-API-Key: ofk_your_api_key"

curl -X POST https://api.ocrforge.co.za/documents \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ofk_your_api_key" \
  -d '{
    "filename": "invoice.pdf",
    "mimeType": "application/pdf",
    "fileSize": 245000,
    "outputFormat": "json",
    "webhookUrl": "https://your-app.com/webhook"
  }'

{
  "job_id": "doc_a1b2c3d4e5f6",
  "status": "awaiting_upload",
  "upload_url": "https://s3.af-south-1.amazonaws.com/...",
  "upload_expires_in": 900,
  "status_url": "/documents/doc_a1b2c3d4e5f6",
  "instructions": "PUT your file to upload_url with the file bytes as body. Then poll status_url for progress."
}

curl https://api.ocrforge.co.za/documents/doc_a1b2c3d4e5f6 \
  -H "X-API-Key: ofk_your_api_key"

{
  "job_id": "doc_a1b2c3d4e5f6",
  "status": "completed",
  "filename": "invoice.pdf",
  "file_size": 245000,
  "mime_type": "application/pdf",
  "output_format": "json",
  "model_used": "textract",
  "pages_total": 3,
  "pages_processed": 3,
  "confidence": 0.94,
  "progress": 100,
  "processing_ms": 4200,
  "result_url": "/documents/doc_a1b2c3d4e5f6/result",
  "created_at": "2026-04-02T09:00:00Z",
  "completed_at": "2026-04-02T09:00:05Z"
}

curl https://api.ocrforge.co.za/documents/doc_a1b2c3d4e5f6/result \
  -H "X-API-Key: ofk_your_api_key"

{
  "job_id": "doc_a1b2c3d4e5f6",
  "status": "completed",
  "download_url": "https://s3.af-south-1.amazonaws.com/...",
  "download_expires_in": 3600,
  "filename": "invoice.pdf",
  "pages": 3,
  "confidence": 0.94,
  "model_used": "textract"
}

curl https://api.ocrforge.co.za/health

{
  "status": "healthy",
  "version": "1.0.0",
  "region": "af-south-1"
}

{
  "error": "Human-readable error description"
}

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
  "error": "Monthly quota exceeded. Upgrade your plan."
}

curl -X POST https://api.ocrforge.co.za/documents \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ofk_your_api_key" \
  -d '{
    "filename": "invoice.pdf",
    "mimeType": "application/pdf",
    "webhookUrl": "https://your-app.com/ocr-callback"
  }'

{
  "event": "document.completed",
  "job_id": "doc_a1b2c3d4e5f6",
  "status": "completed",
  "result_url": "https://api.ocrforge.co.za/documents/doc_a1b2c3d4e5f6/result"
}

{
  "event": "document.failed",
  "job_id": "doc_a1b2c3d4e5f6",
  "status": "failed",
  "error": "OCR processing failed: corrupted image"
}

pip install ocrforge

from ocrforge import OCRForge

client = OCRForge(api_key="ofk_your_api_key")

# Simple: upload, wait, get result
result = client.process("invoice.pdf")
print(result.text)

# Advanced: upload, then poll manually
job = client.upload("invoice.pdf", output_format="json")
job.wait()
print(job.result.text)

npm install ocrforge

const { OCRForge } = require('ocrforge');

const client = new OCRForge({ apiKey: 'ofk_your_api_key' });

// Simple: upload, wait, get result
const result = await client.process('./invoice.pdf');
console.log(result.text);

// Advanced: upload, then poll manually
const job = await client.upload('./invoice.pdf', { outputFormat: 'json' });
await job.waitForCompletion();
console.log(job.result.text);

composer require ocrforge/ocrforge

use OCRForge\Client;

$client = new Client('ofk_your_api_key');

// Simple: upload, wait, get result
$result = $client->process('invoice.pdf');
echo $result->text;

// Advanced: upload, then poll manually
$job = $client->upload('invoice.pdf', ['outputFormat' => 'json']);
$job->waitForCompletion();
echo $job->result->structuredData;

dotnet add package OCRForge

using OCRForge;

var client = new OcrForgeClient("ofk_your_api_key");

// Simple: upload, wait, get result
var result = await client.ProcessAsync("invoice.pdf");
Console.WriteLine(result.Text);

// Advanced: upload, then poll manually
var job = await client.UploadAsync("invoice.pdf", new UploadOptions
{
    OutputFormat = "json"
});
job = await client.WaitForCompletionAsync(job.Id);
var detail = await client.GetResultAsync(job.Id);
Console.WriteLine(detail.DownloadUrl);