Searching documents - LightOn Developers

Search is how your application answers questions from documents. Send a query in plain language, get back ranked passages from across your corpus — no SQL, no keyword matching, no index tuning. Under the hood LightOn runs a hybrid pipeline: vector search for meaning, lexical search for exact terms, then a reranker that scores every candidate against the full query and returns the best results.

This tutorial walks through POST /api/v3/search. For the full schema and every parameter, see the API reference.

Your first search

If you’ve already uploaded documents, this is all you need:

import requests

response = requests.post(
    "https://api.lighton.ai/api/v3/search",
    headers={"Authorization": "Bearer $CONSOLE_API_KEY"},
    json={"query": "What is the JWT token expiry policy"},
)

for result in response.json()["results"]:
    print(result["content"])
    print(f"  → {result['source']['filename']}, p.{result['source']['page_start']}–{result['source']['page_end']}")
    print(f"  → score {result['score']['reranking']:.2f}")

By default this searches every document your API key can reach and returns the top 10 results. That’s usually a good starting point.

Scoping to a subset of documents

When you want to limit search to a specific team’s workspace, a handful of files, or a tagged collection, use one of the three scoping parameters. file_id is mutually exclusive with workspace_id and tag_id — workspace_id and tag_id can be combined.

By workspace
By file
By tag

Best for multi-tenant products where each customer or team has their own workspace.

json={
    "query": "deployment runbook",
    "workspace_id": [12, 15],
}

Best when you know exactly which documents are relevant — for example, after the user selects files in your UI.

json={
    "query": "Q4 revenue forecast",
    "file_id": [101, 102],
}

file_id cannot be combined with workspace_id or tag_id.

Best for curated collections — tag documents at upload time, then search across the collection by tag.

json={
    "query": "GDPR data retention requirements",
    "tag_id": [7],
}

Reading the response

Each result contains four objects:

content — the matched passage text. null for vision-mode chunks.
score — retrieval (always present) and reranking (null when skip_rerank=true).
source — where the chunk came from: file_id, filename, title, mime_type, page_start/page_end, total_pages, tags, and external_metadata for connector-imported files.
workspace — the workspace the document belongs to.

{
  "results": [
    {
      "chunk_id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "JWT tokens are signed using RS256 and expire after 1 hour.",
      "score": {
        "retrieval": 0.92,
        "reranking": 0.95
      },
      "source": {
        "file_id": 512,
        "filename": "auth-system.pdf",
        "title": "Authentication System Design",
        "mime_type": "pdf",
        "size_bytes": 482113,
        "page_start": 3,
        "page_end": 4,
        "total_pages": 12,
        "tags": [{"id": 7, "name": "security"}],
        "external_metadata": null
      },
      "workspace": {"id": 42, "name": "Engineering Docs"}
    }
  ]
}

Tuning result count and latency

max_results (default 10, range 1–50) controls how many ranked chunks come back. For lower latency, set skip_rerank: true. You lose the reranker’s quality boost but the pipeline becomes a straight hybrid lookup, and score.reranking will be null.

json={
    "query": "incident response playbook",
    "max_results": 5,
    "skip_rerank": True,
}

Searching images and diagrams

Switch to vision mode to search documents by their visual content — useful for scanned pages, slide decks, architecture diagrams, or any document where the meaning is in the layout rather than the words.

json={
    "query": "network topology diagram showing DMZ",
    "mode": "vision",
    "include_image": True,
    "max_results": 3,
}

Vision mode requires documents to have been indexed with vision embeddings (status_vision: "embedded"). With include_image: true, each result includes an image.b64_content field with the page rendered as a base64 image. In text mode, the image is fetched from the vision chunk covering the chunk’s start page — empty string if no vision index exists for that page.

Common errors

Status	Cause
`400`	Request body is not parsable JSON
`403`	None of the provided filters resolve to authorized resources
`422`	Validation error — e.g. `file_id` combined with `workspace_id`/`tag_id`, or `max_results` out of range
`429`	Rate limit exceeded
`500`	Unexpected server error

Tutorials

Documentation Index

​Your first search

​Scoping to a subset of documents

​Reading the response

​Tuning result count and latency

​Searching images and diagrams

​Common errors

Your first search

Scoping to a subset of documents

Reading the response

Tuning result count and latency

Searching images and diagrams

Common errors