Search API

Full-text search across OCR text of completed documents owned by the authenticated user.

---

GET /v1/search

Search across all OCR text using PostgreSQL full-text search with stemming and relevance ranking.

Query Parameters:

Parameter	Required	Default	Max	Description
q	Yes	--	--	Search query string
limit	No	50	200	Number of results to return
offset	No	0	--	Number of results to skip

Example:

curl -s "https://api.openesl.com/v1/search?q=dallas+shipping&limit=10" \
  -H "Authorization: Bearer $TOKEN"

Response (200):

{
  "items": [
    {
      "document_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "received_at": "2026-02-21T15:30:16.258193+00:00",
      "snippet": "...BOL Number: BOL-2026-04521\n\nSHIPMENT DETAILS...",
      "score": 7.6
    }
  ],
  "paging": {
    "limit": 10,
    "offset": 0,
    "total": 3
  }
}

Response Fields

Field	Type	Description
document_id	UUID	ID of the matching document
received_at	DateTime	When the document was uploaded
snippet	String	Text excerpt (15-35 words) around the matching terms
score	Float	Relevance score (0-99.9, higher is more relevant)

Search Behavior

• Stemming: "shipping" matches "ship", "shipped", "shipment"
• Case-insensitive: "Dallas" matches "dallas", "DALLAS"
• Stop words: Common English words (the, a, is) are ignored
• Multiple terms: All terms must appear in the document (AND logic)
• Ranking: Results sorted by relevance score (descending)

Scope

• Only searches documents owned by the authenticated user
• Only searches documents with status completed
• Searches the original OCR text (not revised text)

Errors

Status	Code	Condition
400	QUERY_REQUIRED	Missing q parameter
401	UNAUTHORIZED	Missing or invalid token