> ## Documentation Index > Fetch the complete documentation index at: https://developers.lighton.ai/llms.txt > Use this file to discover all available pages before exploring further. # Search document chunks > Embedding → hybrid vector search → optional reranking, returning ranked chunks with provenance. No LLM generation is performed. Billing: 1 retrieval credit per request. **Reranking (`relevance_scoring`):** controls the cross-encoder stage. - `scoring_and_filtering` (default): Score candidates for relevance and only return those above the quality threshold. - `scoring_only`: Score every candidate for relevance but return them all, even low-scoring ones. Useful for building your own filtering logic. - `none`: Skip the relevance scoring step and return all candidates unfiltered. Fastest option, useful when you handle scoring yourself. Omit `relevance_scoring` for the default; send `none` to skip scoring. `skip_rerank` is deprecated — `true` maps to `none`, `false` to `scoring_and_filtering`. **Scoping:** use `workspace_id` and/or `tag_id` to narrow results, or `file_id` to target specific files. `file_id` cannot be combined with `workspace_id` or `tag_id` (422). A 403 is returned when filters resolve to no authorized resources. When no filters are provided, search runs across all documents authorized for the API key. **Facet filtering:** use `content_type` and `attribute` to narrow results by facet metadata. Content type uses colon-separated paths (e.g. `legal:contract:nda`). **Repeated `attribute` entries are ANDed; values inside one entry are ORed with `|` (pipe, recommended).** Example: `attribute=fiscal_year:2024|2025&attribute=status:active` → (fiscal_year 2024 OR 2025) AND (status active). Supports operators (`>`, `>=`, `<`, `<=`), prefix (`name:prefix*`), smart dates, and content-type scoping. **Modes:** - `text` (default): hybrid text search - `vision`: VLM-embedded page image search **Images:** set `include_image=true` to receive a base64-encoded page image with each result. In text mode the image is fetched from the VisionChunk covering the chunk's start page (empty string if no vision index exists for that page). **Bounding boxes (PDF only):** set `include_bboxes=true` to append a `bboxes` array to each result, giving the merged rectangles of the chunk's text on the source PDF (raw PDF points, top-left origin with y extending downward) so you can overlay highlights without re-locating the chunk. One rectangle per logical group; a chunk spanning two pages produces at least one rectangle per page. Available for PDF documents in text mode only — returns an empty list for non-PDF, vision-mode, or pre-v2.2.1 chunks. When `include_bboxes=false` (default) the `bboxes` key is omitted. ## OpenAPI ````yaml /api-reference/api-console.yaml post /api/v3/search openapi: 3.1.0 info: title: LightOn API version: 3.9.0 (v1) description: >- LightOn gives you an API to search, parse, and ingest documents at scale. Build knowledge-retrieval pipelines without managing vector databases or OCR models. servers: - url: https://api.lighton.ai security: [] tags: - name: Ask description: >- Retrieval-augmented generation: search your indexed corpus and generate an LLM answer grounded in the retrieved passages. Supports streaming (SSE) and synchronous modes. - name: Search description: >- Hybrid vector + text retrieval over your indexed corpus. Returns ranked passages with provenance (file, page range, workspace). Optional reranking and vision mode. - name: Files description: Upload, list, fetch, and delete documents indexed in your workspaces. - name: Facets description: >- Organise documents with hierarchical content types and custom attributes per file. Start from starter templates or build your own classification schema from scratch. - name: Tags description: >- Manage flat, company-wide labels used to scope search and group content across workspaces. - name: Workspaces description: >- Create and manage workspaces — the access-controlled containers your documents live in. - name: Parse description: >- Convert documents into structured Markdown — PDFs, images, Office files, and HTML. Synchronous endpoint capped at 20 MB / 15 pages. - name: Extract description: >- Pull typed fields out of documents using a JSON Schema you provide. Sync mode for small documents (≤20 MB / 15 pages); async mode for larger jobs (≤100 MB / 1000 pages) with polling on a job ID. - name: API Keys description: >- Provision and revoke API keys used to authenticate against the Console API. - name: Models description: >- List, register, update, and delete custom ML models scoped to your company. paths: /api/v3/search: post: tags: - Search summary: Search document chunks description: >- Embedding → hybrid vector search → optional reranking, returning ranked chunks with provenance. No LLM generation is performed. Billing: 1 retrieval credit per request. **Reranking (`relevance_scoring`):** controls the cross-encoder stage. - `scoring_and_filtering` (default): Score candidates for relevance and only return those above the quality threshold. - `scoring_only`: Score every candidate for relevance but return them all, even low-scoring ones. Useful for building your own filtering logic. - `none`: Skip the relevance scoring step and return all candidates unfiltered. Fastest option, useful when you handle scoring yourself. Omit `relevance_scoring` for the default; send `none` to skip scoring. `skip_rerank` is deprecated — `true` maps to `none`, `false` to `scoring_and_filtering`. **Scoping:** use `workspace_id` and/or `tag_id` to narrow results, or `file_id` to target specific files. `file_id` cannot be combined with `workspace_id` or `tag_id` (422). A 403 is returned when filters resolve to no authorized resources. When no filters are provided, search runs across all documents authorized for the API key. **Facet filtering:** use `content_type` and `attribute` to narrow results by facet metadata. Content type uses colon-separated paths (e.g. `legal:contract:nda`). **Repeated `attribute` entries are ANDed; values inside one entry are ORed with `|` (pipe, recommended).** Example: `attribute=fiscal_year:2024|2025&attribute=status:active` → (fiscal_year 2024 OR 2025) AND (status active). Supports operators (`>`, `>=`, `<`, `<=`), prefix (`name:prefix*`), smart dates, and content-type scoping. **Modes:** - `text` (default): hybrid text search - `vision`: VLM-embedded page image search **Images:** set `include_image=true` to receive a base64-encoded page image with each result. In text mode the image is fetched from the VisionChunk covering the chunk's start page (empty string if no vision index exists for that page). **Bounding boxes (PDF only):** set `include_bboxes=true` to append a `bboxes` array to each result, giving the merged rectangles of the chunk's text on the source PDF (raw PDF points, top-left origin with y extending downward) so you can overlay highlights without re-locating the chunk. One rectangle per logical group; a chunk spanning two pages produces at least one rectangle per page. Available for PDF documents in text mode only — returns an empty list for non-PDF, vision-mode, or pre-v2.2.1 chunks. When `include_bboxes=false` (default) the `bboxes` key is omitted. operationId: api_v3_search_create requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchRequest' examples: TextSearch—ScopedToWorkspace: value: query: authentication system JWT tokens max_results: 5 workspace_id: - 42 summary: Text search — scoped to workspace description: >- Search within a specific workspace using hybrid text search with reranking. TextSearch—ScopedToFiles: value: query: quarterly revenue forecast max_results: 3 file_id: - 101 - 102 summary: Text search — scoped to files description: Search specific files only. TextSearch—AcrossAllDocuments: value: query: onboarding process max_results: 10 summary: Text search — across all documents description: Search across all documents the API key has access to. SkipRerank—RawRetrieval: value: query: incident response playbook max_results: 10 skip_rerank: true summary: Skip rerank — raw retrieval description: >- Bypass the reranker for lower latency. scores.relevance will be null. TextSearch—WithBoundingBoxes: value: query: authentication system JWT tokens max_results: 5 include_bboxes: true summary: Text search — with bounding boxes description: >- Append merged PDF bounding boxes to each result for overlaying chunk highlights. Facet—ContentTypeFilter: value: query: indemnification clause content_type: - legal:contract max_results: 5 summary: Facet — content type filter description: Search only documents classified as legal contracts. Facet—AttributeFilter: value: query: compliance requirements workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: >- Search documents with specific attribute values, combined with workspace scoping. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SearchRequest' examples: TextSearch—ScopedToWorkspace: value: query: authentication system JWT tokens max_results: 5 workspace_id: - 42 summary: Text search — scoped to workspace description: >- Search within a specific workspace using hybrid text search with reranking. TextSearch—ScopedToFiles: value: query: quarterly revenue forecast max_results: 3 file_id: - 101 - 102 summary: Text search — scoped to files description: Search specific files only. TextSearch—AcrossAllDocuments: value: query: onboarding process max_results: 10 summary: Text search — across all documents description: Search across all documents the API key has access to. SkipRerank—RawRetrieval: value: query: incident response playbook max_results: 10 skip_rerank: true summary: Skip rerank — raw retrieval description: >- Bypass the reranker for lower latency. scores.relevance will be null. TextSearch—WithBoundingBoxes: value: query: authentication system JWT tokens max_results: 5 include_bboxes: true summary: Text search — with bounding boxes description: >- Append merged PDF bounding boxes to each result for overlaying chunk highlights. Facet—ContentTypeFilter: value: query: indemnification clause content_type: - legal:contract max_results: 5 summary: Facet — content type filter description: Search only documents classified as legal contracts. Facet—AttributeFilter: value: query: compliance requirements workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: >- Search documents with specific attribute values, combined with workspace scoping. multipart/form-data: schema: $ref: '#/components/schemas/SearchRequest' examples: TextSearch—ScopedToWorkspace: value: query: authentication system JWT tokens max_results: 5 workspace_id: - 42 summary: Text search — scoped to workspace description: >- Search within a specific workspace using hybrid text search with reranking. TextSearch—ScopedToFiles: value: query: quarterly revenue forecast max_results: 3 file_id: - 101 - 102 summary: Text search — scoped to files description: Search specific files only. TextSearch—AcrossAllDocuments: value: query: onboarding process max_results: 10 summary: Text search — across all documents description: Search across all documents the API key has access to. SkipRerank—RawRetrieval: value: query: incident response playbook max_results: 10 skip_rerank: true summary: Skip rerank — raw retrieval description: >- Bypass the reranker for lower latency. scores.relevance will be null. TextSearch—WithBoundingBoxes: value: query: authentication system JWT tokens max_results: 5 include_bboxes: true summary: Text search — with bounding boxes description: >- Append merged PDF bounding boxes to each result for overlaying chunk highlights. Facet—ContentTypeFilter: value: query: indemnification clause content_type: - legal:contract max_results: 5 summary: Facet — content type filter description: Search only documents classified as legal contracts. Facet—AttributeFilter: value: query: compliance requirements workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: >- Search documents with specific attribute values, combined with workspace scoping. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SearchResponse' examples: TextSearchResult—WithRerankingAndFacetData: value: results: - chunk_id: 550e8400-e29b-41d4-a716-446655440000 content: >- The indemnifying party shall hold harmless and indemnify the other party... score: 0.92 scores: text: 0.91 vision: null keyword: 0.43 multivector: 0.78 relevance: 0.95 source: file_id: 512 filename: customer-nda.pdf title: Customer NDA — Nimbus Labs mime_type: pdf size_bytes: 482113 page_start: 3 page_end: 4 total_pages: 12 tags: - id: 7 name: confidential content_types: - path: legal:contract:nda label: Non-Disclosure Agreement attribute_values: jurisdiction: value: - FR - US type: multi-select is_mutual: value: true type: boolean counterparty: value: Nimbus Labs type: text external_metadata: null workspace: id: 42 name: Legal Team summary: Text search result — with reranking and facet data description: >- Search with reranking applied (default). scores.relevance reflects reranker confidence. Source includes compact content_types with attribute values. TextSearchResult—SkipRerank: value: results: - chunk_id: 550e8400-e29b-41d4-a716-446655440000 content: >- JWT tokens are signed using RS256 and expire after 1 hour. score: 0.87 scores: text: 0.91 vision: null keyword: 0.43 multivector: 0.78 relevance: null 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 content_types: [] external_metadata: null workspace: id: 42 name: Engineering Docs summary: Text search result — skip rerank description: >- Raw retrieval without reranking (skip_rerank=true). scores.relevance is null. TextSearchResult—WithBoundingBoxes: value: results: - chunk_id: 550e8400-e29b-41d4-a716-446655440000 content: >- JWT tokens are signed using RS256 and expire after 1 hour. score: 0.92 scores: text: 0.91 vision: null keyword: 0.43 multivector: 0.78 relevance: 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 content_types: [] external_metadata: null workspace: id: 42 name: Engineering Docs bboxes: - page_number: 3 x: 47.37 'y': 528.28 width: 280.13 height: 95.42 unit: pdf_point origin: top_left - page_number: 4 x: 41.86 'y': 98 width: 285.99 height: 158.67 unit: pdf_point origin: top_left summary: Text search result — with bounding boxes description: >- Response when include_bboxes=true. Each result gains a bboxes array of merged rectangles in PDF points (top-left origin, y extending downward). A chunk spanning pages 3 and 4 yields at least one rectangle per page. Empty list for vision/non-PDF/pre-v2.2.1 chunks. NoMatchingDocuments: value: results: [] summary: No matching documents description: Query returned no results — empty array with HTTP 200. description: Ranked search results. Empty array if no documents match. '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: BadRequest: value: code: 400 error: bad_request detail: The request body could not be parsed as valid JSON. summary: Bad request description: Request body is not parsable JSON. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: code: 401 error: unauthorized detail: >- Authentication credentials were not provided or are invalid. description: Missing or invalid API key. '403': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InsufficientPermissions: value: code: 403 error: insufficient_permissions detail: >- None of the provided filters resolve to authorized resources. summary: Insufficient permissions description: API key has no authorized resources matching the provided filters. '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError—ScopingConflict: value: code: 422 error: validation_error detail: One or more fields failed validation. fields: file_id: - error: invalid_combination detail: >- file_id cannot be combined with workspace_id or tag_id. summary: Validation error — scoping conflict ValidationError—MaxResultsOutOfRange: value: code: 422 error: validation_error detail: One or more fields failed validation. fields: max_results: - error: too_large detail: Ensure this value is less than or equal to 50. summary: Validation error — max_results out of range description: Field validation failure. '429': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: TooManyRequests: value: code: 429 error: rate_limit_exceeded detail: Request was throttled. summary: Too many requests description: Rate limit exceeded. '500': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: InternalServerError: value: code: 500 error: internal_server_error detail: An unexpected error occurred. Please try again later. summary: Internal server error description: Unexpected server error. security: - bearerAuth: [] components: schemas: SearchRequest: type: object description: >- DRF serializer mixin providing ``content_type`` and ``attribute`` fields. Compose into any request serializer via multiple inheritance:: class SearchRequestSerializer(FacetFilterFieldsMixin, serializers.Serializer): query = serializers.CharField(...) # content_type and attribute inherited from the mixin properties: content_type: type: array items: type: string description: >- Filter by content type path. Multiple values are OR. Exact-or-subtree matching by default (e.g. `legal` matches legal, legal:contract). Wildcards: `*contract*` (contains), `legal:contract*` (prefix). attribute: type: array items: type: string description: >- Filter by attribute value. **Repeated `attribute` entries are ANDed; values inside one entry are ORed with `|`** (pipe is the recommended OR delimiter — comma also works but can be ambiguous with multi-key values). Example: `attribute=fiscal_year:2024|2025&attribute=status:active` → (fiscal_year 2024 OR 2025) AND (status active). Formats: `name` (has any value), `name:value` (exact), `name:>value` / `name:>=value` (gt/gte), `name:- Restrict to documents carrying any of these tag IDs (OR). Cannot combine with file_id. file_id: type: array items: type: integer description: >- Restrict to specific file IDs. Cannot combine with workspace_id or tag_id. mode: allOf: - $ref: '#/components/schemas/ModeEnum' default: text description: >- "text": hybrid keyword + vector search. "vision": VLM-embedded page image search. * `text` - text * `vision` - vision relevance_scoring: allOf: - $ref: '#/components/schemas/RelevanceScoringEnum' description: >- Controls the cross-encoder relevance scoring step. "scoring_and_filtering" (default): Score candidates for relevance and only return those above the quality threshold. When no candidate clears the threshold, the few best-scoring candidates are returned instead of an empty result; their scores.relevance is then below the usual threshold. "scoring_only": Score every candidate for relevance but return them all, even low-scoring ones. Useful for building your own filtering logic. "none": Skip the relevance scoring step and return all candidates unfiltered. Fastest option, useful when you handle scoring yourself. Omit the field for the default; send "none" to skip. Overrides skip_rerank when both are sent. * `none` - none * `scoring_only` - scoring_only * `scoring_and_filtering` - scoring_and_filtering skip_rerank: type: boolean description: >- Deprecated — use relevance_scoring. true → relevance_scoring=none, false → relevance_scoring=scoring_and_filtering. Ignored when relevance_scoring is provided. include_image: type: boolean default: false description: Append a base64-encoded page image to each result. include_bboxes: type: boolean default: false description: >- Append merged bounding boxes (in PDF points, top-left origin) to each result so callers can overlay chunk highlights on PDF pages. PDF documents in text mode only — non-PDF and vision-mode results always return an empty list. Omitted from the response entirely when false. required: - query SearchResponse: type: object properties: results: type: array items: $ref: '#/components/schemas/SearchResultItem' description: Ranked search results. explain: type: object additionalProperties: {} description: >- Scoring breakdown. Present only when explain=true and SEARCH_EXPLAIN_MODE is enabled. required: - results APIV3ErrorResponse: type: object properties: id: type: - string - 'null' description: >- Job/resource id when one already exists (useful for async error diagnosis); null otherwise. code: type: integer description: HTTP status code error: type: string description: Error code used by the UI as a translation key detail: type: string description: Human-readable error message for developers doc_url: type: string description: Link to the error-code documentation page required: - code - detail - doc_url - error - id APIV3ValidationErrorResponse: type: object properties: id: type: - string - 'null' description: >- Job/resource id when one already exists (useful for async error diagnosis); null otherwise. code: type: integer description: HTTP status code error: type: string description: Error code used by the UI as a translation key detail: type: string description: Human-readable error message for developers doc_url: type: string description: Link to the error-code documentation page fields: type: object additionalProperties: type: array items: $ref: '#/components/schemas/APIV3FieldError' description: Field-level validation errors keyed by field name required: - code - detail - doc_url - error - id ModeEnum: enum: - text - vision type: string description: |- * `text` - text * `vision` - vision RelevanceScoringEnum: enum: - none - scoring_only - scoring_and_filtering type: string description: |- * `none` - none * `scoring_only` - scoring_only * `scoring_and_filtering` - scoring_and_filtering SearchResultItem: type: object properties: chunk_id: type: string format: uuid description: Chunk UUID. content: type: - string - 'null' description: Chunk text content. Null for vision-mode chunks. score: type: number format: double description: Overall fused relevance score. scores: allOf: - $ref: '#/components/schemas/SearchScores' description: Per-signal score breakdown for this chunk. image: allOf: - $ref: '#/components/schemas/SearchImage' description: Page image. Present only when include_image=true. source: allOf: - $ref: '#/components/schemas/SearchSource' description: Source document metadata. workspace: oneOf: - $ref: '#/components/schemas/SearchWorkspace' - type: 'null' description: Workspace the document belongs to. bboxes: type: array items: $ref: '#/components/schemas/SearchBbox' description: >- Merged bounding boxes for the chunk's text on the source PDF. Present only when include_bboxes=true. Empty list for vision-mode, non-PDF, or pre-v2.2.1 chunks. required: - chunk_id - content - score - scores - source - workspace APIV3FieldError: type: object properties: error: type: string description: Error code / translation key detail: type: string description: Human-readable description of the field error required: - detail - error SearchScores: type: object properties: text: type: - number - 'null' format: double description: Dense text embedding similarity (1 - distance). Null in vision mode. vision: type: - number - 'null' format: double description: Vision page similarity. Null when the document has no vision index. keyword: type: - number - 'null' format: double description: BM25 lexical score. Null in vision mode. multivector: type: - number - 'null' format: double description: >- ColBERT multi-vector (MaxSim) score. Null when multi-vector reranking is disabled. relevance: type: - number - 'null' format: double description: >- Cross-encoder reranker confidence. Populated for every returned chunk in scoring_only and scoring_and_filtering modes. Null when relevance_scoring is "none" (equivalently the deprecated skip_rerank=true) or when the reranker is unavailable. required: - keyword - multivector - relevance - text - vision SearchImage: type: object properties: b64_content: type: string description: >- Base64-encoded page image. Empty string when no vision index exists for the page. required: - b64_content SearchSource: type: object properties: file_id: type: integer description: File ID. filename: type: string description: Original filename. title: type: - string - 'null' description: Document title. mime_type: type: - string - 'null' description: File type (e.g. pdf, docx). size_bytes: type: - integer - 'null' description: File size in bytes. page_start: type: - integer - 'null' description: Start page of the chunk (1-indexed). page_end: type: - integer - 'null' description: End page of the chunk (1-indexed). total_pages: type: integer description: Total pages in the document. tags: type: array items: $ref: '#/components/schemas/SearchTag' description: Tags associated with the document. content_types: type: array items: type: object additionalProperties: {} description: Facet content type classifications and attribute values. external_metadata: oneOf: - $ref: '#/components/schemas/SearchExternalMetadata' - type: 'null' description: >- Null for directly-uploaded documents; present for connector-imported documents. required: - external_metadata - file_id - filename - mime_type - page_end - page_start - size_bytes - tags - title - total_pages SearchWorkspace: type: object properties: id: type: integer description: Workspace ID. name: type: string description: Workspace name. required: - id - name SearchBbox: type: object properties: page_number: type: integer description: 1-indexed page the rectangle sits on. x: type: number format: double description: Left edge in PDF points, top-left origin. 'y': type: number format: double description: Top edge in PDF points, top-left origin (y extends downward). width: type: number format: double description: Width in PDF points. height: type: number format: double description: Height in PDF points. unit: type: string description: Coordinate unit. Always "pdf_point" in v1. origin: type: string description: Coordinate origin. Always "top_left" in v1. required: - height - origin - page_number - unit - width - x - 'y' SearchTag: type: object properties: id: type: integer description: Tag ID. name: type: string description: Tag name. required: - id - name SearchExternalMetadata: type: object properties: external_id: type: string description: ID of the document in the external system. external_url: type: - string - 'null' description: >- Deep-link back to the document in the source system. Null if not provided. additional_metadata: type: object additionalProperties: {} description: >- Freeform connector metadata. external_url is lifted to its own field and excluded here. required: - additional_metadata - external_id - external_url securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your auth token. ````