OCR API Integration — Complete Developer Guide

Cargoffer OCR is a REST API with Bearer token authentication. The extraction workflow has two steps: upload a document via POST /api/upload, then analyze it via POST /api/analyze/job_name. The result is a structured JSON object with all extracted fields plus a verified boolean indicating 2-pass confirmation.

Get your API key by signing up on the web or via POST /api/signup with your email. Pass the key in the Authorization header as Bearer ocr_your_api_key. For web applications, Clerk JWT tokens are also accepted the API detects the token type automatically.

POST /api/upload accepts multipart form data with a file field. Supported formats: PDF, PNG, JPG, TIFF, XLSX, EML. Maximum file size is 50 MB. The response returns a job name that you use in the next step. Upload errors return 400 for invalid files and 422 for unsupported formats.

POST /api/analyze/job_name triggers the extraction. The system selects the best model based on document type: Gemini for PDF (native vision), DeepSeek for structured data like XLSX, and GLM for images. Progress can be tracked via the GET /api/jobs endpoint.

The API returns standard HTTP status codes: 401 for invalid or missing API key, 402 for quota exceeded with a message to upgrade your plan, 429 for rate limiting with a Retry-After header, and 422 for malformed requests. Always handle these errors in your integration code.

Store API keys in environment variables, never in client-side code. Use the document hash for caching same documents cost nothing to re-extract. Process multiple documents concurrently for higher throughput. Set reasonable timeouts of 60 seconds for large documents.