API Documentation

Reference for OCR request formats, response contracts, failure modes, and service health.

POST/api/ocr

Multipart/Form-Data

Runs OCR on uploaded image files and/or remote image URLs. Returns one result item per input in processing order.

Parameters

imagesfile[]required: NoOne or more multipart image files. Field name must be exactly `images`.
urlsstring (JSON)required: NoJSON array string of remote image URLs, for example: `["https://site/a.png"]`. Field name must be `urls`.

Behavior Notes

At least one input is expected (`images` or `urls`).
Each URL fetch has a timeout of approximately 5 seconds.
On per-item failure, API still returns `200` with an item-level `error` message.
Only unexpected server failures return `500` with:{ "error": "OCR Server Failed Internally." }

Example Request (Files)

curl -X POST http://localhost:3000/api/ocr \
  -F "images=@screenshot.png" \
  -F "images=@document.jpg"

Example Request (URLs)

curl -X POST http://localhost:3000/api/ocr \
  -F 'urls=["https://example.com/a.png","https://example.com/b.jpg"]'

Example Request (Mixed)

curl -X POST http://localhost:3000/api/ocr \
  -F "images=@scan.png" \
  -F 'urls=["https://example.com/remote.jpg"]'

Example Response (Success)

{
  "results": [
    {
      "name": "invoice.png",
      "type": "file",
      "text": ["Invoice #1021", "Total: $120.00"],
      "time": 0.38
    },
    {
      "name": "https://example.com/receipt.jpg",
      "type": "url",
      "text": ["Store Name", "Amount 54.20"],
      "time": 0.41
    }
  ],
  "totalTime": 0.91
}

Example Response (Partial Failure)

{
  "results": [
    {
      "name": "broken-image.jpg",
      "type": "file",
      "error": "Processing failed",
      "time": 0
    },
    {
      "name": "https://bad-domain.test/a.png",
      "type": "url",
      "error": "Invalid URL or Image",
      "time": 0
    }
  ],
  "totalTime": 0.12
}

GET/api/ocr

Application/JSON

Returns lightweight server state for monitoring queue load and processing activity.

Example Response

{
  "status": "ok",
  "queueLength": 0,
  "processing": false
}