OCR, document intelligence, and DAM search

​

Goal

​

Prerequisites

• A PDF or image asset
• An assets:process token to start or retry extraction and assets:read to read results or search
• The English language pack for the shipped eng runtime; additional Tesseract language data must exist before requesting another code

​

Workflow

​

Provider behavior and supported input

• The production provider is poppler_tesseract; its cache identity includes the installed Poppler and Tesseract engine versions.
• For a PDF, pdftotext -bbox-layout first extracts embedded text and word boxes. If the document has no usable embedded text, pdftoppm renders every page and Tesseract OCRs the PNG pages.
• For an image MIME type, Tesseract processes one page directly.
• The default language is eng. The only current option is dpi for rasterized PDFs; it defaults to 200 and is clamped to 72–400.

​

Start, read, and retry

const extraction = await stackshift.assets.text.start(asset.id, {
  language: 'eng',
  options: { dpi: 240 },
})

let current = await stackshift.assets.text.get(asset.id)
while (current.status === 'pending' || current.status === 'processing') {
  await new Promise((resolve) => setTimeout(resolve, 2000))
  current = await stackshift.assets.text.get(asset.id)
}
if (current.status === 'failed') {
  console.error(current.error_code, current.error_message)
  await stackshift.assets.text.retry(current.id)
}

stackshift asset ocr-start ASSET_UUID --wait --data '{"language":"eng","options":{"dpi":240}}' --output json
stackshift asset ocr-get ASSET_UUID --output json
stackshift asset ocr-retry EXTRACTION_UUID --output json

​

Result schema and geometry

• box is [left, top, right, bottom], normalized to 0–1 relative to the page.
• Tesseract confidence is normalized from 0–100 to 0–1. Embedded PDF words have confidence 1 because no OCR probability is involved.
• Page dimensions remain useful for projecting normalized boxes into pixels, canvas coordinates, or PDF viewer coordinates.

{
  "status": "ready",
  "plain_text": "Invoice total 42.00",
  "page_count": 1,
  "pages": [{
    "number": 1,
    "width": 1275,
    "height": 1650,
    "blocks": [{
      "text": "Invoice",
      "type": "word",
      "confidence": 0.97,
      "box": [0.10, 0.22, 0.24, 0.27]
    }]
  }]
}

​

Automatic extraction, cache identity, and versions

• Bucket automation defaults off. Set auto_extract_text: true through the revision-checked storage configuration endpoint; it applies to future supported uploads and replacements.
• The cache key is tenant-scoped and includes asset SHA-256, provider, engine version, language, and canonical options hash. Identical content in one Assets space can reuse a result without cross-tenant disclosure.
• The extraction is linked to the current asset version. Replacing bytes changes the checksum/version and therefore creates or links the correct cache entry naturally.
• A failed extraction records error_code and error_message, emits an OCR failure event, and remains retryable. It never changes asset readiness, scan state, visibility, or delivery.

​

Search extracted text

const results = await stackshift.assets.list({
  query: '"invoice total" 42.00',
  status: 'ready',
  limit: 50,
})

​

Expected result

​

Common failures

​

Related guides