Preview API¶

The preview endpoint streams safe previews for indexed image documents. It is mainly used by the web UI, but custom clients can call it too.

Authentication is required.

Endpoint¶

GET /api/documents/{document_id}/preview

Use the document ID from a search result or from GET /api/documents/{document_id}.

curl -L http://localhost:8000/api/documents/documents--abc123def456/preview \
  -H "Authorization: Bearer $TOKEN" \
  --output preview.jpg

The endpoint supports:

RAW previews do not decode sensor data. OneSearch scans for embedded JPEG previews and returns the best one it can find.

Preview errors return a structured detail object:

{
  "detail": {
    "code": "preview_too_large",
    "message": "Preview file exceeds 50 MB limit"
  }
}

Common codes:

Code	Meaning
`previews_disabled`	Previews are disabled in settings.
`document_not_found`	No indexed document exists for that ID.
`source_not_found`	The document's source no longer exists.
`path_outside_source`	The indexed path is outside its configured source root.
`file_not_found`	The source file moved or was deleted after indexing.
`preview_too_large`	The source file is larger than the configured preview limit.
`raw_preview_disabled`	RAW previews are disabled.
`raw_preview_unavailable`	No embedded RAW preview could be extracted.
`unsupported_preview_type`	The document type does not have a streamed preview.

Preview behavior is controlled by the Settings API and Admin → Settings → File Previews: