API Reference

Use the StartOCR HTTP API to submit images and PDFs from your own applications.

OpenAPI document: /api/openapi.json

Authentication

Create an API key from Settings → API Keys (sign in first). Choose scopes:

Scope	Access
submit	POST /api/ocr (always included)
read	GET /api/tasks, GET /api/tasks/:id, GET /api/export/...
export	DELETE /api/tasks/:id

Authorization: Bearer YOUR_API_KEY

Submit a job

POST https://startocr.com/api/ocr
Content-Type: application/json

Request body

Field	Type	Required	Description
imageBase64	string	Yes	Base64-encoded file bytes, or a data:image/...;base64,... data URI
filename	string	No	Original filename (used for type detection)
provider	"paddle-ai-studio" | "baidu"	No	OCR engine. Defaults to "paddle-ai-studio"
documentType	"general" | "invoice"	No	When "invoice", task metadata includes extracted invoice fields after OCR

Success response

{
  "success": true,
  "taskId": "clx...",
  "provider": "paddle-ai-studio"
}

Get a task

Requires read scope.

GET https://startocr.com/api/tasks/{taskId}

When status is done, the payload includes resultText.

List tasks

GET https://startocr.com/api/tasks?page=1&pageSize=20&status=done

Delete a task

Requires export scope.

DELETE https://startocr.com/api/tasks/{taskId}

Export a result

Requires read scope. Formats: docx, xlsx, pdf.

GET https://startocr.com/api/export/{taskId}/docx

Webhooks

Configure HTTPS endpoints in Settings → Webhooks. Events:

• ocr.done
• ocr.failed

Headers:

• X-Webhook-Signature: sha256=<hex>
• X-Webhook-Timestamp
• X-Webhook-Nonce

Verify with HMAC-SHA256 over `${timestamp}.${nonce}.${rawBody}` using the endpoint signing secret.

Providers

• paddle-ai-studio (default) — async queue processing. Poll GET /api/tasks/:id until done or use webhooks.
• baidu — synchronous OCR with word-level positions when available.

Billing

Each submission deducts pages based on the document page count before processing starts. Business plan members share the owner's balance. If task creation fails after deduction, pages are refunded automatically.

Errors

HTTP	error code	Meaning
401	missing_api_key / invalid_api_key	Auth failed
403	user_banned / insufficient_scope	Banned or missing scope
402	insufficient_pages	No remaining page balance
404	not_found	Task not found
413	payload_too_large	Body exceeds 10 MB
429	rate_limited / daily_quota_exceeded	Throttled
415	unsupported_media_type	Wrong content type or file magic

CORS

Browser-based calls must originate from an allowed domain. Server-to-server integrations do not require CORS configuration.