> ## Documentation Index > Fetch the complete documentation index at: https://docs.lighton.ai/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve document chunks > **Deprecated: Use the v3 search endpoint instead.** Invoke the document retrieval pipeline (embedding + hybrid vector search + reranking) and return matched document chunks. **Relevance scoring (`relevance_scoring`):** controls the relevance scoring stage. - `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 `relevance_scoring` for the default; send `none` to skip scoring. `skip_rerank` is **deprecated** — `true` maps to `relevance_scoring=none`, `false` to `scoring_and_filtering`. `relevance_scoring` wins if both are sent. **Result ordering:** results are returned in descending order of `score`. With `scoring_and_filtering` or `scoring_only`, `score` equals the relevance score (`scores.relevance`, 0–1). With `none`, `score` is the combined retrieval score (higher is better, no fixed upper bound). If the scoring model is temporarily unavailable, results are returned in retrieval order and a `warnings` array is included. 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 when all pipeline steps succeed. **Scoping:** use `workspace_id` and/or `tag_id` to narrow retrieval to specific workspaces or tags, or use `file_id` to target specific files. `file_id` cannot be combined with `workspace_id` or `tag_id`. A 403 is returned if any provided filter resolves to no authorized resources. When no filters are provided, retrieval runs across all authorized documents. **Public datasets:** a public dataset workspace must be the only workspace in the request — combining it with any other `workspace_id`, `file_id`, or `tag_id` returns 400. Public datasets are reachable only through a workspace-scoped API key whose scope includes the workspace, and only for companies allowed to access them; otherwise the result is empty. **Facet filtering:** use `content_type` and/or `attribute` to narrow retrieval by document metadata. These can be combined with workspace/tag scoping. Content type uses colon-separated paths (e.g. `legal:contract:nda`). Attributes support operators, OR, and content-type scoping. **Modes:** - `text` (default): hybrid text search - `vision`: image-based search **Explain mode:** set `explain=true` to receive a per-chunk scoring breakdown in the response (raw scores, normalized scores, fusion weights, filter stats, timing). Requires the `SEARCH_EXPLAIN_MODE` feature flag to be enabled. ## OpenAPI ````yaml /api-reference/openapi-v3.yaml post /api/v3/retrieve openapi: 3.1.0 info: title: LightOn API version: 3.15.0 (v3) 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://paradigm.lighton.ai security: [] tags: - name: Agents description: Operations about agents - name: Threads description: Operations about agents conversation threads - name: Tools description: Operations about native tools - name: Models description: Operations about AI models - name: MCP description: Operations about MCP servers - name: Sources description: Operations about sources used by agents conversation threads - name: Artifacts description: Operations about artifacts generated by agents conversation threads - name: Agent description: >- Operations about agents (deprecated). Please use the 'Agents' API component instead. - name: Files description: Operations about files - name: Facets description: Operations about facets - name: Tags description: Operations about tags - name: Workspaces description: Operations about workspaces - name: Files Processing description: Operations about files processing - name: Users description: Operations about users - name: API Keys description: Operations about API keys - name: User Groups description: Operations about user groups - name: SCIM description: Operations about SCIM paths: /api/v3/retrieve: post: tags: - Files Processing summary: Retrieve document chunks description: >- **Deprecated: Use the v3 search endpoint instead.** Invoke the document retrieval pipeline (embedding + hybrid vector search + reranking) and return matched document chunks. **Relevance scoring (`relevance_scoring`):** controls the relevance scoring stage. - `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 `relevance_scoring` for the default; send `none` to skip scoring. `skip_rerank` is **deprecated** — `true` maps to `relevance_scoring=none`, `false` to `scoring_and_filtering`. `relevance_scoring` wins if both are sent. **Result ordering:** results are returned in descending order of `score`. With `scoring_and_filtering` or `scoring_only`, `score` equals the relevance score (`scores.relevance`, 0–1). With `none`, `score` is the combined retrieval score (higher is better, no fixed upper bound). If the scoring model is temporarily unavailable, results are returned in retrieval order and a `warnings` array is included. 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 when all pipeline steps succeed. **Scoping:** use `workspace_id` and/or `tag_id` to narrow retrieval to specific workspaces or tags, or use `file_id` to target specific files. `file_id` cannot be combined with `workspace_id` or `tag_id`. A 403 is returned if any provided filter resolves to no authorized resources. When no filters are provided, retrieval runs across all authorized documents. **Public datasets:** a public dataset workspace must be the only workspace in the request — combining it with any other `workspace_id`, `file_id`, or `tag_id` returns 400. Public datasets are reachable only through a workspace-scoped API key whose scope includes the workspace, and only for companies allowed to access them; otherwise the result is empty. **Facet filtering:** use `content_type` and/or `attribute` to narrow retrieval by document metadata. These can be combined with workspace/tag scoping. Content type uses colon-separated paths (e.g. `legal:contract:nda`). Attributes support operators, OR, and content-type scoping. **Modes:** - `text` (default): hybrid text search - `vision`: image-based search **Explain mode:** set `explain=true` to receive a per-chunk scoring breakdown in the response (raw scores, normalized scores, fusion weights, filter stats, timing). Requires the `SEARCH_EXPLAIN_MODE` feature flag to be enabled. operationId: api_v3_retrieve_create requestBody: content: application/json: schema: $ref: '#/components/schemas/RetrieveRequest' examples: TextMode—ScopedToWorkspace: value: query: authentication system JWT tokens mode: text top_k: 20 workspace_id: - 42 summary: Text mode — scoped to workspace description: >- Retrieve chunks from a specific workspace using hybrid text search with reranking. TextMode—ScopedToFiles: value: query: quarterly revenue forecast mode: text top_k: 10 file_id: - 101 - 102 summary: Text mode — scoped to files description: Retrieve chunks from specific files only. TextMode—AcrossAllDocuments: value: query: onboarding process mode: text top_k: 20 summary: Text mode — across all documents description: >- Retrieve chunks across all documents the API key has access to. VisionModeWithImage: value: query: architecture diagram mode: vision top_k: 10 include_image: true summary: Vision mode with image description: >- Retrieve vision chunks (images/diagrams) using image-based search. SkipScoring(none)—RawRetrieval: value: query: incident response playbook mode: text top_k: 20 relevance_scoring: none summary: Skip scoring (none) — raw retrieval description: >- Bypass the reranker to isolate raw vector + lexical retrieval quality. ScoringOnly—RerankWithoutFiltering: value: query: incident response playbook mode: text top_k: 20 relevance_scoring: scoring_only summary: Scoring only — rerank without filtering description: >- Score every candidate for relevance but return them all, even low-scoring ones. Useful for building your own filtering logic. Facet—ContentTypeFilter: value: query: indemnification clause content_type: - legal:contract top_k: 20 summary: Facet — content type filter description: Retrieve only from 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: >- Retrieve from documents with a specific attribute value, combined with workspace scoping. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/RetrieveRequest' examples: TextMode—ScopedToWorkspace: value: query: authentication system JWT tokens mode: text top_k: 20 workspace_id: - 42 summary: Text mode — scoped to workspace description: >- Retrieve chunks from a specific workspace using hybrid text search with reranking. TextMode—ScopedToFiles: value: query: quarterly revenue forecast mode: text top_k: 10 file_id: - 101 - 102 summary: Text mode — scoped to files description: Retrieve chunks from specific files only. TextMode—AcrossAllDocuments: value: query: onboarding process mode: text top_k: 20 summary: Text mode — across all documents description: >- Retrieve chunks across all documents the API key has access to. VisionModeWithImage: value: query: architecture diagram mode: vision top_k: 10 include_image: true summary: Vision mode with image description: >- Retrieve vision chunks (images/diagrams) using image-based search. SkipScoring(none)—RawRetrieval: value: query: incident response playbook mode: text top_k: 20 relevance_scoring: none summary: Skip scoring (none) — raw retrieval description: >- Bypass the reranker to isolate raw vector + lexical retrieval quality. ScoringOnly—RerankWithoutFiltering: value: query: incident response playbook mode: text top_k: 20 relevance_scoring: scoring_only summary: Scoring only — rerank without filtering description: >- Score every candidate for relevance but return them all, even low-scoring ones. Useful for building your own filtering logic. Facet—ContentTypeFilter: value: query: indemnification clause content_type: - legal:contract top_k: 20 summary: Facet — content type filter description: Retrieve only from 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: >- Retrieve from documents with a specific attribute value, combined with workspace scoping. multipart/form-data: schema: $ref: '#/components/schemas/RetrieveRequest' examples: TextMode—ScopedToWorkspace: value: query: authentication system JWT tokens mode: text top_k: 20 workspace_id: - 42 summary: Text mode — scoped to workspace description: >- Retrieve chunks from a specific workspace using hybrid text search with reranking. TextMode—ScopedToFiles: value: query: quarterly revenue forecast mode: text top_k: 10 file_id: - 101 - 102 summary: Text mode — scoped to files description: Retrieve chunks from specific files only. TextMode—AcrossAllDocuments: value: query: onboarding process mode: text top_k: 20 summary: Text mode — across all documents description: >- Retrieve chunks across all documents the API key has access to. VisionModeWithImage: value: query: architecture diagram mode: vision top_k: 10 include_image: true summary: Vision mode with image description: >- Retrieve vision chunks (images/diagrams) using image-based search. SkipScoring(none)—RawRetrieval: value: query: incident response playbook mode: text top_k: 20 relevance_scoring: none summary: Skip scoring (none) — raw retrieval description: >- Bypass the reranker to isolate raw vector + lexical retrieval quality. ScoringOnly—RerankWithoutFiltering: value: query: incident response playbook mode: text top_k: 20 relevance_scoring: scoring_only summary: Scoring only — rerank without filtering description: >- Score every candidate for relevance but return them all, even low-scoring ones. Useful for building your own filtering logic. Facet—ContentTypeFilter: value: query: indemnification clause content_type: - legal:contract top_k: 20 summary: Facet — content type filter description: Retrieve only from 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: >- Retrieve from documents with a specific attribute value, combined with workspace scoping. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/RetrieveV3Response' examples: TextModeResult—WithRerankingAndFacetScoping: value: query: indemnification clause retrieve_params: mode: text top_k: 20 relevance_scoring: scoring_and_filtering skip_rerank: false include_image: false explain: false scoping_params: file_id: [] tag_id: [] workspace_id: - 42 content_type: - legal:contract attribute: - jurisdiction:FR results: - chunk: id: 1024 uuid: 550e8400-e29b-41d4-a716-446655440000 content_id: content_id_550e8400-e29b-41d4-a716-446655440000 text: >- The indemnifying party shall hold harmless and indemnify the other party... chunk_type: text metadata: pages: 3-4 total_pages: 12 title: Customer NDA — Nimbus Labs source: customer-nda.pdf parser: v2.2.1 folder_name: legal/customers coords: 3,72.0,120.0,450.0,18.0;4,72.0,80.0,450.0,18.0 previous: 550e8400-e29b-41d4-a716-446655440002 next: 550e8400-e29b-41d4-a716-446655440004 overlapping: '' token_length: 412 created_at: '2025-11-01T09:00:00Z' updated_at: '2025-11-01T09:00:00Z' scoring: score: 0.95 scores: text: 0.92 vision: 0.12 keyword: 0.74 multivector: 0.81 relevance: 0.95 workspace: id: 42 name: Legal Team workspace_type: custom document: id: 512 name: customer-nda.pdf file_type: pdf status: embedded total_pages: 12 uploaded_at: '2025-10-30T08:00:00Z' title: Customer NDA — Nimbus Labs tags: - id: 7 name: confidential auto_assigned: true external_metadata: external_id: legal-doc-456789 doc_type: nda additional_metadata: external_url: https://contracts.example.com/legal/customer-nda 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 summary: Text mode result — with reranking and facet scoping description: >- Retrieval with reranking applied (relevance_scoring="scoring_and_filtering", default) and facet filters. score equals scores.relevance (relevance score). Document includes compact content_types with attribute values. TextModeResult—RawRetrieval: value: query: JWT authentication retrieve_params: mode: text top_k: 20 relevance_scoring: none skip_rerank: true include_image: false explain: false scoping_params: file_id: [] tag_id: [] workspace_id: [] content_type: [] attribute: [] results: - chunk: id: 1024 uuid: 550e8400-e29b-41d4-a716-446655440000 content_id: content_id_550e8400-e29b-41d4-a716-446655440000 text: >- JWT tokens are signed using RS256 and expire after 1 hour. chunk_type: text metadata: pages: '3' total_pages: 12 title: Authentication System Design source: auth-system.pdf parser: v2.2.1 folder_name: engineering/security coords: 3,72.0,120.0,450.0,18.0 previous: '' next: 550e8400-e29b-41d4-a716-446655440002 overlapping: '' token_length: 380 created_at: '2025-11-01T09:00:00Z' updated_at: '2025-11-01T09:00:00Z' scoring: score: 1.65 scores: text: 0.92 vision: 0.12 keyword: 0.74 multivector: 0.81 relevance: null workspace: id: 42 name: Engineering Docs workspace_type: custom document: id: 512 name: auth-system.pdf file_type: pdf status: embedded total_pages: 12 uploaded_at: '2025-10-30T08:00:00Z' title: Authentication System Design tags: - id: 7 name: security auto_assigned: false external_metadata: null content_types: [] summary: Text mode result — raw retrieval description: >- Raw retrieval without reranking (relevance_scoring="none"). score is the combined retrieval score (higher is better, no fixed upper bound). scores.relevance is null. VisionModeResult: value: query: architecture diagram retrieve_params: mode: vision top_k: 20 relevance_scoring: scoring_and_filtering skip_rerank: false include_image: true explain: false scoping_params: file_id: [] tag_id: [] workspace_id: [] content_type: [] attribute: [] results: - chunk: id: 2048 uuid: 661f9511-f3ac-52e5-b827-557766551111 metadata: pages: '4' total_pages: 20 title: Infrastructure Overview source: infra-overview.pdf parser: vision folder_name: '' coords: null previous: '' next: '' overlapping: '' token_length: null created_at: '2025-11-02T10:00:00Z' updated_at: '2025-11-02T10:00:00Z' scoring: score: 0.88 scores: text: null vision: 0.85 keyword: null multivector: null relevance: 0.88 workspace: id: 42 name: Engineering Docs workspace_type: custom document: id: 513 name: infra-overview.pdf file_type: pdf status: embedded total_pages: 20 uploaded_at: '2025-10-31T08:00:00Z' title: Infrastructure Overview tags: [] external_metadata: null content_types: [] corresponding_image: b64_content: iVBORw0KGgo... summary: Vision mode result description: Vision chunk result with base64-encoded image. TextModeResult—WithIncludeDetails: value: query: compliance requirements retrieve_params: mode: text top_k: 20 relevance_scoring: scoring_and_filtering skip_rerank: false include_image: false explain: false scoping_params: file_id: [] tag_id: [] workspace_id: [] content_type: - legal attribute: [] results: - chunk: id: 2050 uuid: 771fa622-g4bd-63f6-c938-668877662222 content_id: content_id_771fa622-g4bd-63f6-c938-668877662222 text: >- All data processing must comply with GDPR Article 28... chunk_type: text metadata: pages: '5' total_pages: 18 title: GDPR Compliance Policy source: gdpr-compliance-policy.pdf parser: v2.2.1 folder_name: legal/compliance coords: 5,72.0,420.0,450.0,18.0 previous: 771fa622-g4bd-63f6-c938-668877662221 next: 771fa622-g4bd-63f6-c938-668877662223 overlapping: '' token_length: 295 created_at: '2025-11-03T11:00:00Z' updated_at: '2025-11-03T11:00:00Z' scoring: score: 0.91 scores: text: 0.88 vision: null keyword: 0.69 multivector: null relevance: 0.91 workspace: id: 3 name: Legal Team workspace_type: custom document: id: 514 name: gdpr-compliance-policy.pdf file_type: pdf status: embedded total_pages: 18 uploaded_at: '2025-11-01T08:00:00Z' title: GDPR Compliance Policy tags: - id: 15 name: compliance auto_assigned: false external_metadata: null content_types: - code: compliance path: legal:compliance label: Compliance breadcrumb: - code: legal path: legal label: Legal - code: compliance path: legal:compliance label: Compliance attribute_values: regulation: value: - GDPR type: multi-select attribute: name: regulation label: Regulation type: multi-select required: false choices: - GDPR - SOX - HIPAA - AML - KYC jurisdiction: value: - FR - DE type: multi-select attribute: name: jurisdiction label: Jurisdiction type: multi-select required: false choices: - FR - US - UK - DE - CH summary: Text mode result — with include_details description: >- Response when include_details=true. Content types gain code, structured breadcrumb (ancestor chain), and expanded attribute_values with full attribute definitions (name, label, type, required, choices). TextModeResult—RerankerUnavailable: value: query: authentication system JWT tokens retrieve_params: mode: text top_k: 20 relevance_scoring: scoring_and_filtering skip_rerank: false include_image: false explain: false scoping_params: file_id: [] tag_id: [] workspace_id: - 42 content_type: [] attribute: [] results: - chunk: id: 1024 uuid: 550e8400-e29b-41d4-a716-446655440000 content_id: content_id_550e8400-e29b-41d4-a716-446655440000 text: >- JWT tokens are signed using RS256 and expire after 1 hour. chunk_type: text metadata: pages: '3' total_pages: 12 title: Authentication System Design source: auth-system.pdf parser: v2.2.1 folder_name: '' coords: 3,72.0,120.0,450.0,18.0 previous: '' next: '' overlapping: '' token_length: 380 created_at: '2025-11-01T09:00:00Z' updated_at: '2025-11-01T09:00:00Z' scoring: score: 1.65 scores: text: 0.92 vision: null keyword: 0.74 multivector: 0.81 relevance: null workspace: id: 42 name: Engineering Docs workspace_type: custom document: id: 512 name: auth-system.pdf file_type: pdf status: embedded total_pages: 12 uploaded_at: '2025-10-30T08:00:00Z' title: Authentication System Design tags: [] external_metadata: null content_types: [] warnings: - code: relevance reason: model_not_found summary: Text mode result — reranker unavailable description: >- Reranker failed; results returned in retrieval order. score falls back to the combined retrieval score (no fixed upper bound) and scores.relevance is null. The warnings array identifies the degraded signal and failure reason. NoMatchingDocuments: value: query: quantum computing patents retrieve_params: mode: text top_k: 20 relevance_scoring: scoring_and_filtering skip_rerank: false include_image: false explain: false scoping_params: file_id: [] tag_id: [] workspace_id: [] content_type: [] attribute: [] results: [] summary: No matching documents description: >- Query returned no results — empty array with HTTP 200. Full envelope is always present. description: Chunks retrieved successfully. Empty array if no documents match. '400': description: A public dataset workspace was combined with other scope filters. '401': description: Authentication credentials were not provided or are invalid. '403': description: >- A provided filter (workspace_id, file_id, or tag_id) does not exist or the user is not authorized to access it. '422': content: application/json: schema: $ref: '#/components/schemas/APIV3ValidationErrorResponse' examples: ValidationError: value: id: null code: 422 error: validation_error detail: One or more fields failed validation. doc_url: https://developers.lighton.ai/errors#validation_error fields: : - error: required detail: This field is required. summary: Validation Error description: Request body is valid JSON but one or more fields failed validation '429': description: Rate limit exceeded. '503': description: >- API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry. content: application/json: schema: $ref: '#/components/schemas/ServiceMaintenance503' deprecated: true security: - bearerAuth: [] components: schemas: RetrieveRequest: 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:- Retrieval pipeline: "text" (hybrid search on DocumentChunk) or "vision" (image-based on VisionChunk). * `text` - text * `vision` - vision top_k: type: integer maximum: 100 minimum: 1 default: 20 description: >- Number of best candidates to score and return. Relevance scoring evaluates all top_k candidates from retrieval; scoring_and_filtering then keeps only those above the quality threshold. Range: 1–100. workspace_id: type: array items: type: integer description: Scope retrieval to specific workspace IDs (authorized only). file_id: type: array items: type: integer description: Scope retrieval to specific file IDs (authorized only). tag_id: type: array items: type: integer description: >- Scope retrieval to documents with any of these tag IDs (company-scoped). relevance_scoring: allOf: - $ref: '#/components/schemas/RelevanceScoringEnum' description: >- Controls the 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: Include base64-encoded page image in each result. include_details: type: boolean default: false description: >- Expand document metadata in results. When true, content types include breadcrumb, code, and attribute definitions (type, required, choices). required: - query RetrieveV3Response: type: object properties: query: type: string description: The search query that was executed. retrieve_params: allOf: - $ref: '#/components/schemas/RetrieveParams' description: Retrieval parameters used (including defaults). scoping_params: allOf: - $ref: '#/components/schemas/ScopingParams' description: Scoping parameters used to narrow retrieval. results: type: array items: $ref: '#/components/schemas/RetrieveResultItem' description: Retrieved chunks with context, ordered by score descending. warnings: type: array items: $ref: '#/components/schemas/RetrieveWarning' description: >- Present only when a pipeline signal degrades. Absent in the happy path. required: - query - results - retrieve_params - scoping_params 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 ServiceMaintenance503: type: object description: >- Returned by the maintenance middleware when the requested endpoint is blocked. required: - detail - error - mode properties: detail: type: string example: System is under maintenance. error: type: string example: service_maintenance mode: type: string enum: - full_shutdown - warning_banner description: >- `full_shutdown` blocks all traffic; `warning_banner` also blocks and shows a dismissible toast. reason: type: string description: Operator-supplied maintenance reason, if any. started_at: type: string format: date-time endpoint_category_names: type: array items: type: string description: >- Non-empty only for category-scoped periods. Empty means all endpoints are affected. 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 RetrieveParams: type: object properties: mode: type: string description: 'Retrieval mode used: "text" or "vision".' top_k: type: integer description: Number of best candidates scored and returned. relevance_scoring: type: string description: >- Cross-encoder mode used: 'none' (skip), 'scoring_only', or 'scoring_and_filtering'. skip_rerank: type: boolean description: >- Deprecated — derived from relevance_scoring (true when relevance_scoring is 'none'). include_image: type: boolean description: Whether page images are included. required: - include_image - mode - relevance_scoring - skip_rerank - top_k ScopingParams: type: object properties: file_id: type: array items: type: integer description: File IDs used for scoping. tag_id: type: array items: type: integer description: Tag IDs used for scoping. workspace_id: type: array items: type: integer description: Workspace IDs used for scoping. content_type: type: array items: type: string description: Content type paths used for scoping. attribute: type: array items: type: string description: Attribute filters used for scoping. required: - file_id - tag_id - workspace_id RetrieveResultItem: type: object properties: chunk: allOf: - $ref: '#/components/schemas/RetrieveChunk' readOnly: true description: >- Chunk data. Text mode: id, uuid, content_id, text, chunk_type, metadata, created_at, updated_at. Vision mode: id, uuid, metadata, created_at, updated_at. scoring: allOf: - $ref: '#/components/schemas/RetrieveScoring' description: Relevance scores for this chunk workspace: oneOf: - $ref: '#/components/schemas/WorkspaceInFileResponseSerializerV3' - type: 'null' description: >- Workspace the document belongs to. Null if the document has no workspace. document: allOf: - $ref: '#/components/schemas/RetrieveDocument' description: Source document corresponding_image: allOf: - $ref: '#/components/schemas/RetrieveCorrespondingImage' description: Page image (present when include_image=true) required: - chunk - document - scoring - workspace RetrieveWarning: 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 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 RetrieveChunk: oneOf: - $ref: '#/components/schemas/RetrieveTextChunk' - $ref: '#/components/schemas/RetrieveVisionChunk' RetrieveScoring: type: object properties: 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/RetrieveScores' description: Per-signal score breakdown. required: - score - scores WorkspaceInFileResponseSerializerV3: type: object description: Minimal workspace info for file responses. properties: id: type: integer description: Workspace ID name: type: string description: Workspace name workspace_type: type: string description: Workspace type (shared or personal) required: - id - name - workspace_type RetrieveDocument: type: object properties: id: type: integer readOnly: true name: type: string readOnly: true description: Document filename file_type: type: - string - 'null' maxLength: 30 status: $ref: '#/components/schemas/DocumentStatusEnum' total_pages: type: integer readOnly: true description: Total number of pages uploaded_at: type: string format: date-time readOnly: true title: type: - string - 'null' maxLength: 255 tags: type: array items: $ref: '#/components/schemas/TagItem' readOnly: true description: Tags associated with the document external_metadata: oneOf: - $ref: '#/components/schemas/RetrieveDocumentExternalMetadata' - type: 'null' readOnly: true description: External metadata, if any content_types: type: array items: $ref: '#/components/schemas/DocumentFacetCompactSchema' readOnly: true description: Content type classifications and attribute values required: - content_types - external_metadata - id - name - tags - total_pages - uploaded_at RetrieveCorrespondingImage: type: object properties: b64_content: type: string description: >- Base64-encoded page image. Empty string when the image is unavailable. required: - b64_content RetrieveTextChunk: type: object properties: id: type: integer readOnly: true uuid: type: string format: uuid content_id: type: - string - 'null' maxLength: 255 text: type: string chunk_type: $ref: '#/components/schemas/ChunkTypeEnum' metadata: allOf: - $ref: '#/components/schemas/ChunkMetadataResponse' readOnly: true description: >- Provenance and positioning metadata: page range, title, source filename, and neighbouring chunk UUIDs. created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true required: - created_at - id - metadata - text - updated_at - uuid RetrieveVisionChunk: type: object properties: id: type: integer readOnly: true uuid: type: string format: uuid metadata: allOf: - $ref: '#/components/schemas/ChunkMetadataResponse' readOnly: true description: >- Provenance and positioning metadata: page, title, source filename. `coords` and `token_length` are null for vision chunks. created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true required: - created_at - id - metadata - updated_at - uuid RetrieveScores: 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 DocumentStatusEnum: enum: - pending - pending_conversion - converting - parsing - parsing_failed - embedding - embedding_failed - embedded - parsed - fail - updating type: string description: |- * `pending` - Pending * `pending_conversion` - Pending Conversion * `converting` - Converting * `parsing` - Parsing * `parsing_failed` - Parsing Failed * `embedding` - Embedding * `embedding_failed` - Embedding Failed * `embedded` - Embedded * `parsed` - Parsed * `fail` - Fail * `updating` - Updating TagItem: type: object description: Serializer for tag items in file list response. properties: id: type: integer description: Tag ID name: type: string description: Tag name auto_assigned: type: boolean description: >- True if this tag was automatically assigned by the system, False if manually assigned by a user required: - auto_assigned - id - name RetrieveDocumentExternalMetadata: type: object properties: external_id: type: string description: External document ID doc_type: type: string title: External document type maxLength: 255 additional_metadata: oneOf: - {} - type: 'null' required: - external_id DocumentFacetCompactSchema: type: object description: >- OpenAPI schema for compact content type response (Tier 1 — list default). properties: path: type: string description: Colon-separated content type path (e.g. legal:contract:nda) label: type: string description: User-readable label (leaf node) attribute_values: type: object additionalProperties: $ref: '#/components/schemas/DocumentFacetAttributeValueSchema' description: >- Map of attribute name to {value, type}. Only present when include_details=true. required: - label - path ChunkTypeEnum: enum: - text - table type: string description: |- * `text` - text * `table` - table ChunkMetadataResponse: description: >- Provenance and positioning metadata returned alongside every retrieved chunk. properties: pages: default: '' description: >- 1-indexed page (or page range) of the parent document covered by the chunk. Single page: '5'. Multi-page span: '3-4'. title: Pages type: string total_pages: anyOf: - type: integer - type: 'null' default: null description: >- Total page count of the parent document. Null when unknown (e.g. spreadsheets). title: Total Pages title: default: '' description: Parent document's title. Empty when the document has no title. title: Title type: string source: default: '' description: Original filename of the parent document, e.g. 'design-doc.pdf'. title: Source type: string parser: default: '' description: Parser that produced the chunk (e.g. 'vision' for vision chunks). title: Parser type: string folder_name: default: '' description: >- Name of the immediate folder the document was imported from. Empty for direct uploads. title: Folder Name type: string coords: anyOf: - type: string - type: 'null' default: null description: >- Bounding boxes of the chunk's text on the source PDF, as a semicolon-joined string of 'page,x,y,w,h' tuples (e.g. '3,72.0,120.0,450.0,18.0;3,72.0,140.0,450.0,18.0'). Null when unavailable (spreadsheets, vision chunks). title: Coords previous: default: '' description: >- UUID of the previous chunk in the document. Empty for the first chunk. title: Previous type: string next: default: '' description: UUID of the next chunk in the document. Empty for the last chunk. title: Next type: string overlapping: default: '' description: >- Semicolon-joined UUIDs of chunks that share text with this chunk. Empty when there is no overlap. title: Overlapping type: string token_length: anyOf: - type: integer - type: 'null' default: null description: Number of tokens in the chunk text. Null for vision chunks. title: Token Length title: ChunkMetadataResponse type: object DocumentFacetAttributeValueSchema: type: object description: OpenAPI schema for a compact attribute value entry. properties: value: description: Attribute value (type depends on attribute definition) type: type: string description: Attribute type (text, number, date, boolean, select, multi_select) label: type: string description: User-readable attribute label (present when include_details=true) required: - type - value securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your auth token. ````