> ## 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. # Ask a question over your documents > Retrieval-augmented generation: searches your indexed corpus, then generates an LLM answer grounded in the retrieved passages. **Modes:** - `stream=false` (default): returns a single JSON response with `results` and `answer`. - `stream=true`: returns Server-Sent Events — `event: sources` (retrieved chunks), `event: token` (answer tokens), `event: done` (stream complete), or `event: error` (generation failure). **Model:** defaults to `mistral-large-latest` (flagship, best answer quality). Pass `model=alfred-ft5` for the lighter, faster LightOn fine-tune. Company-specific custom models (`custom-{company_id}-{uuid}`) are also accepted. Any other value returns 422. **Relevance scoring:** relevance scoring always runs in `scoring_and_filtering` mode — candidates are scored for relevance and only those above the quality threshold are used as context. `score` equals the relevance score (`scores.relevance`, 0–1). Results are returned in descending order of `score`. If the scoring model is temporarily unavailable, `score` falls back to the combined retrieval score (higher is better, no fixed upper bound) and `scores.relevance` is null. **Scoping:** same rules as `/api/v3/search` — 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). **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. If the reranker is temporarily unavailable, results are returned in retrieval order and each result item includes a `warnings` array. Each warning has a `code` matching the degraded `scores` key (e.g. `relevance`) and a `reason` classifying the failure: `model_not_found`, `timeout`, `service_error`, or `unknown`. The `warnings` key is absent from result items when all pipeline steps succeed. Billing: 1 search-with-generation credit per request. ## OpenAPI ````yaml /api-reference/api-console.yaml post /api/v3/ask openapi: 3.1.0 info: title: LightOn API version: 3.12.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: Budget description: >- Manage your organization's monthly spend budget and alert thresholds. Set a hard cap that blocks API requests when reached, and configure email notifications at custom spend percentages. paths: /api/v3/ask: post: tags: - Ask summary: Ask a question over your documents description: >- Retrieval-augmented generation: searches your indexed corpus, then generates an LLM answer grounded in the retrieved passages. **Modes:** - `stream=false` (default): returns a single JSON response with `results` and `answer`. - `stream=true`: returns Server-Sent Events — `event: sources` (retrieved chunks), `event: token` (answer tokens), `event: done` (stream complete), or `event: error` (generation failure). **Model:** defaults to `mistral-large-latest` (flagship, best answer quality). Pass `model=alfred-ft5` for the lighter, faster LightOn fine-tune. Company-specific custom models (`custom-{company_id}-{uuid}`) are also accepted. Any other value returns 422. **Relevance scoring:** relevance scoring always runs in `scoring_and_filtering` mode — candidates are scored for relevance and only those above the quality threshold are used as context. `score` equals the relevance score (`scores.relevance`, 0–1). Results are returned in descending order of `score`. If the scoring model is temporarily unavailable, `score` falls back to the combined retrieval score (higher is better, no fixed upper bound) and `scores.relevance` is null. **Scoping:** same rules as `/api/v3/search` — 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). **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. If the reranker is temporarily unavailable, results are returned in retrieval order and each result item includes a `warnings` array. Each warning has a `code` matching the degraded `scores` key (e.g. `relevance`) and a `reason` classifying the failure: `model_not_found`, `timeout`, `service_error`, or `unknown`. The `warnings` key is absent from result items when all pipeline steps succeed. Billing: 1 search-with-generation credit per request. operationId: api_v3_ask_create requestBody: content: application/json: schema: $ref: '#/components/schemas/AskRequest' examples: DefaultModel—ScopedToWorkspace: value: query: How are JWT tokens signed? max_results: 5 workspace_id: - 42 summary: Default model — scoped to workspace description: >- Ask a question within a specific workspace using the default model. AlternateModel—ScopedToFiles: value: query: What is the quarterly revenue forecast? max_results: 3 file_id: - 101 - 102 model: alfred-ft5 summary: Alternate model — scoped to files description: >- Ask using the lighter alfred-ft5 model, targeting specific files. StreamingMode: value: query: Summarize the onboarding process stream: true summary: Streaming mode description: Stream the answer as Server-Sent Events. Facet—ContentTypeFilter: value: query: What are the indemnification terms? content_type: - legal:contract max_results: 5 summary: Facet — content type filter description: Ask only over documents classified as legal contracts. Facet—AttributeFilter: value: query: What are the compliance requirements? workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: >- Ask over documents with specific attribute values, combined with workspace scoping. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/AskRequest' examples: DefaultModel—ScopedToWorkspace: value: query: How are JWT tokens signed? max_results: 5 workspace_id: - 42 summary: Default model — scoped to workspace description: >- Ask a question within a specific workspace using the default model. AlternateModel—ScopedToFiles: value: query: What is the quarterly revenue forecast? max_results: 3 file_id: - 101 - 102 model: alfred-ft5 summary: Alternate model — scoped to files description: >- Ask using the lighter alfred-ft5 model, targeting specific files. StreamingMode: value: query: Summarize the onboarding process stream: true summary: Streaming mode description: Stream the answer as Server-Sent Events. Facet—ContentTypeFilter: value: query: What are the indemnification terms? content_type: - legal:contract max_results: 5 summary: Facet — content type filter description: Ask only over documents classified as legal contracts. Facet—AttributeFilter: value: query: What are the compliance requirements? workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: >- Ask over documents with specific attribute values, combined with workspace scoping. multipart/form-data: schema: $ref: '#/components/schemas/AskRequest' examples: DefaultModel—ScopedToWorkspace: value: query: How are JWT tokens signed? max_results: 5 workspace_id: - 42 summary: Default model — scoped to workspace description: >- Ask a question within a specific workspace using the default model. AlternateModel—ScopedToFiles: value: query: What is the quarterly revenue forecast? max_results: 3 file_id: - 101 - 102 model: alfred-ft5 summary: Alternate model — scoped to files description: >- Ask using the lighter alfred-ft5 model, targeting specific files. StreamingMode: value: query: Summarize the onboarding process stream: true summary: Streaming mode description: Stream the answer as Server-Sent Events. Facet—ContentTypeFilter: value: query: What are the indemnification terms? content_type: - legal:contract max_results: 5 summary: Facet — content type filter description: Ask only over documents classified as legal contracts. Facet—AttributeFilter: value: query: What are the compliance requirements? workspace_id: - 42 content_type: - legal attribute: - jurisdiction:FR - effective_date:>2024-01-01 summary: Facet — attribute filter description: >- Ask over documents with specific attribute values, combined with workspace scoping. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AskResponse' examples: SynchronousAnswer—WithFacetData: value: results: - chunk_id: 550e8400-e29b-41d4-a716-446655440000 content: >- JWT tokens are signed using RS256 and expire after 1 hour. score: 0.95 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: - path: engineering:security label: Security attribute_values: topic: value: authentication type: text external_metadata: null workspace: id: 42 name: Engineering Docs answer: >- Based on the authentication system design document, JWT tokens are signed using RS256 and have a 1-hour expiration (auth-system.pdf, page 3). summary: Synchronous answer — with facet data description: >- Complete answer with source chunks. Source includes content_types with attribute values when documents have facet classifications. SynchronousAnswer—RerankerUnavailable: value: results: - chunk_id: 550e8400-e29b-41d4-a716-446655440000 content: >- JWT tokens are signed using RS256 and expire after 1 hour. score: 1.65 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: [] content_types: [] external_metadata: null workspace: id: 42 name: Engineering Docs warnings: - code: relevance reason: model_not_found answer: >- Based on the available documents, JWT tokens are signed using RS256 and have a 1-hour expiration. Note: relevance scoring was unavailable for this request. summary: Synchronous answer — reranker unavailable description: >- Reranker degraded; each result item carries a warnings array. score falls back to the combined retrieval score (no fixed upper bound) and scores.relevance is null. The warnings key is absent when healthy. SynchronousAnswer—NoFacets: value: results: - chunk_id: 550e8400-e29b-41d4-a716-446655440000 content: >- JWT tokens are signed using RS256 and expire after 1 hour. score: 0.95 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 answer: >- Based on the authentication system design document, JWT tokens are signed using RS256 and have a 1-hour expiration (auth-system.pdf, page 3). summary: Synchronous answer — no facets description: Answer with source chunks without facet content type data. description: >- Synchronous mode (`stream=false`): complete answer with sources. Streaming mode (`stream=true`): Server-Sent Events with `event: sources`, `event: token`, and `event: done` (or `event: error`). '400': content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' 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/CommonErrorResponse' 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/CommonErrorResponse' 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. '404': content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' examples: ModelUnavailableOnBackend: value: code: 404 error: not_found detail: Model 'mistral-large-latest' not found. summary: Model unavailable on backend description: >- A supported model (`mistral-large-latest` or `alfred-ft5`) is not currently available on the backend. (An unsupported `model` value is rejected earlier with a 422.) '422': content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' 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—UnsupportedModel: value: code: 422 error: validation_error detail: One or more fields failed validation. fields: model: - error: invalid_choice detail: '"gpt-4" is not a valid choice.' summary: Validation error — unsupported model description: Field validation failure. '429': content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' examples: TooManyRequests: value: code: 429 error: too_many_requests detail: Request was throttled. summary: Too many requests description: Rate limit exceeded. '500': content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' 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. '503': content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' examples: ModelUnavailable: value: code: 503 error: model_unavailable detail: >- The model is temporarily unavailable. Please try again later. summary: Model unavailable description: Model temporarily unavailable. '504': content: application/json: schema: $ref: '#/components/schemas/CommonErrorResponse' examples: ModelTimeout: value: code: 504 error: model_timeout detail: The model did not respond in time. Please try again later. summary: Model timeout description: Model timeout. security: - bearerAuth: [] components: schemas: AskRequest: 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. relevance_scoring: allOf: - $ref: '#/components/schemas/RelevanceScoringEnum' default: scoring_and_filtering description: >- Controls the relevance scoring step used during retrieval. "none": Skip scoring — lowest latency, relevance score is null in each result. "scoring_only": Score every candidate but return them all. Omit for the default (score and filter). * `none` - none * `scoring_only` - scoring_only * `scoring_and_filtering` - scoring_and_filtering stream: type: boolean default: false description: When true, response is streamed as Server-Sent Events. model: type: string default: mistral-large-latest description: >- LLM used for answer generation. Standard values: - `mistral-large-latest`: Mistral Large 2 — flagship general-purpose model. Best answer quality (default). - `alfred-ft5`: Alfred FT5 — LightOn fine-tuned model, lighter and faster for straightforward questions. Custom model technical names (e.g. `custom-{company_id}-{uuid}`) are also accepted. required: - query AskResponse: type: object properties: results: type: array items: $ref: '#/components/schemas/AskResultItem' description: >- Retrieved chunks used as context, ordered by relevance score descending. answer: type: string description: LLM-generated answer grounded in the retrieved results. required: - answer - results CommonErrorResponse: type: object properties: error: type: string required: - error RelevanceScoringEnum: enum: - none - scoring_only - scoring_and_filtering type: string description: |- * `none` - none * `scoring_only` - scoring_only * `scoring_and_filtering` - scoring_and_filtering AskResultItem: 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: >- Effective relevance score — the sort key. Equals scores.relevance (0–1) when relevance scoring ran, otherwise the combined retrieval score (higher is better, no fixed upper bound). Results are ordered by this value descending. scores: allOf: - $ref: '#/components/schemas/SearchScores' description: Per-signal score breakdown. 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. warnings: type: array items: $ref: '#/components/schemas/SearchWarning' description: >- Present only when a pipeline signal degrades. Absent in the happy path. required: - chunk_id - content - score - scores - source - workspace SearchScores: type: object properties: text: type: - number - 'null' format: double description: >- Semantic text similarity (0–1, higher is better). Null in vision mode. vision: type: - number - 'null' format: double description: >- Vision page similarity (0–1, higher is better). Null when the document has no vision index. keyword: type: - number - 'null' format: double description: >- Keyword match score (higher is better, no fixed upper bound). Null in vision mode. multivector: type: - number - 'null' format: double description: >- Token-level similarity score (higher is better, no fixed upper bound). Null when multi-vector scoring is disabled. relevance: type: - number - 'null' format: double description: >- Relevance score (0–1, higher is better). Populated when relevance_scoring is "scoring_only" or "scoring_and_filtering". Null when relevance_scoring is "none" or when the scoring model 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' SearchWarning: type: object properties: code: type: string description: Signal name from the scores object that degraded (e.g. 'relevance'). reason: type: string description: >- Machine-readable failure reason (model_not_found, timeout, service_error, unknown). required: - code 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. ````