> ## 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. # Resolve search scope > Resolves content type and attribute filters from a natural-language query. Call this **before** `/search`, `/ask`, or `/files` to narrow results by domain. Pass the inferred `content_type` and `attribute` directly to those endpoints. Returns ranked content types grouped by root schema, each with a relevance score and the attribute definitions available for filtering. ### Scores and decision signal Each content type in the response includes a `score` (relevance to your query). Use scores to decide how to scope your search — higher means stronger match. `has_signal` is a convenience shortcut: it's `true` when the top score meets a default confidence threshold. For custom logic, use `score` directly and apply your own threshold via the `threshold` request parameter. ### Three modes **1. Prompt mode** (default) — returns `prompt_context`, a self-contained LLM-ready text block. Feed it to any LLM alongside the user query to infer `content_type` and `attribute` filters. The prompt includes ranked content types, attribute definitions with filter syntax, inference rules, date ranges, and few-shot examples. **2. Completion mode** — pass `model` (technical name) and the API calls the LLM for you. Returns `scope_completion` with parsed, normalized filters: - Label-to-name mapping (e.g. "Filing Date" → `filing_date`) - Syntax validation against the attribute schema - Structured JSON output via guided decoding - `warnings` for any normalization applied or issues detected - If the LLM call fails, `scope_completion` is still returned with `warnings` explaining the failure — the rest of the response remains usable. **3. Catalog + completion mode** — set `relevance_scoring: "none"` with a `query` and `model` to get the full content type catalog AND an LLM-inferred `scope_completion`. Useful when you want the LLM to choose from ALL content types without retrieval pre-filtering. `max_results` and `threshold` are ignored. ### Response fields | Field | Description | |-------|-------------| | `score` | Relevance score. Higher = better match. Comparable across requests. | | `max_score` | Highest score in a root group. Compare roots without iterating. | | `chunk_count` | Retrieval chunks matching this CT. More chunks = broader evidence. | | `doc_count` | Total corpus documents classified under this CT. | | `prompt_context` | LLM-ready prompt text. Pass to your LLM as-is. | | `prompt_version` | Fingerprint (`t:.d:`) for eval reproducibility. | | `scope_completion` | Parsed LLM output (only when `model` is provided). | ### Schema context mode Omit `query` to get the full content type catalog — useful for system prompts, tool descriptions, or schema exploration. `groups` contains all content types with their attributes (`score=0`, `chunk_count=0` since there is no query to rank against). `prompt_context` contains the same catalog as LLM-ready text. ### Integration notes - Content type paths use `:` as separator (e.g. `patent:electricity:h04`). - Attribute filter syntax is documented in `prompt_context` per attribute type. Date ranges use `>=` / `<=` operators (e.g. `filing_date:>=2023-01-01`). - Writing meaningful attribute descriptions (especially for person-name and code/identifier fields) improves the quality of `prompt_context` hints. ## OpenAPI ````yaml /api-reference/api-console.yaml post /api/v3/content-types/scope openapi: 3.1.0 info: title: LightOn API version: 3.15.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/content-types/scope: post: tags: - Facets summary: Resolve search scope description: >- Resolves content type and attribute filters from a natural-language query. Call this **before** `/search`, `/ask`, or `/files` to narrow results by domain. Pass the inferred `content_type` and `attribute` directly to those endpoints. Returns ranked content types grouped by root schema, each with a relevance score and the attribute definitions available for filtering. ### Scores and decision signal Each content type in the response includes a `score` (relevance to your query). Use scores to decide how to scope your search — higher means stronger match. `has_signal` is a convenience shortcut: it's `true` when the top score meets a default confidence threshold. For custom logic, use `score` directly and apply your own threshold via the `threshold` request parameter. ### Three modes **1. Prompt mode** (default) — returns `prompt_context`, a self-contained LLM-ready text block. Feed it to any LLM alongside the user query to infer `content_type` and `attribute` filters. The prompt includes ranked content types, attribute definitions with filter syntax, inference rules, date ranges, and few-shot examples. **2. Completion mode** — pass `model` (technical name) and the API calls the LLM for you. Returns `scope_completion` with parsed, normalized filters: - Label-to-name mapping (e.g. "Filing Date" → `filing_date`) - Syntax validation against the attribute schema - Structured JSON output via guided decoding - `warnings` for any normalization applied or issues detected - If the LLM call fails, `scope_completion` is still returned with `warnings` explaining the failure — the rest of the response remains usable. **3. Catalog + completion mode** — set `relevance_scoring: "none"` with a `query` and `model` to get the full content type catalog AND an LLM-inferred `scope_completion`. Useful when you want the LLM to choose from ALL content types without retrieval pre-filtering. `max_results` and `threshold` are ignored. ### Response fields | Field | Description | |-------|-------------| | `score` | Relevance score. Higher = better match. Comparable across requests. | | `max_score` | Highest score in a root group. Compare roots without iterating. | | `chunk_count` | Retrieval chunks matching this CT. More chunks = broader evidence. | | `doc_count` | Total corpus documents classified under this CT. | | `prompt_context` | LLM-ready prompt text. Pass to your LLM as-is. | | `prompt_version` | Fingerprint (`t:.d:`) for eval reproducibility. | | `scope_completion` | Parsed LLM output (only when `model` is provided). | ### Schema context mode Omit `query` to get the full content type catalog — useful for system prompts, tool descriptions, or schema exploration. `groups` contains all content types with their attributes (`score=0`, `chunk_count=0` since there is no query to rank against). `prompt_context` contains the same catalog as LLM-ready text. ### Integration notes - Content type paths use `:` as separator (e.g. `patent:electricity:h04`). - Attribute filter syntax is documented in `prompt_context` per attribute type. Date ranges use `>=` / `<=` operators (e.g. `filing_date:>=2023-01-01`). - Writing meaningful attribute descriptions (especially for person-name and code/identifier fields) improves the quality of `prompt_context` hints. operationId: api_v3_content_types_scope_create requestBody: content: application/json: schema: $ref: '#/components/schemas/FacetScopeRequest' examples: BasicScopeQuery: value: query: rejected electronics patents summary: Basic scope query WithCustomMaxResults: value: query: mutual NDA expiring 2025 max_results: 5 summary: With custom max_results SchemaContext(noQuery): value: {} summary: Schema context (no query) description: Omit query to get the full CT catalog as prompt_context. WithLLMCompletion: value: query: patents from Q1 2023 model: mistral/mistral-large-latest summary: With LLM completion description: Pass model to get scope_completion with parsed filters. AllCTs+LLMCompletion(noScoring): value: query: employment contracts from last year model: mistral/mistral-large-latest relevance_scoring: none summary: All CTs + LLM completion (no scoring) description: >- relevance_scoring="none" returns all content types without retrieval ranking, with LLM completion over the full catalog. responses: '200': content: application/json: schema: $ref: '#/components/schemas/FacetScopeResponse' examples: StrongMatch—SingleRoot: value: has_signal: true groups: - root: patent root_label: Patent Classification max_score: 1.72 content_types: - path: patent:electricity label: Electricity root: patent score: 1.72 chunk_count: 12 doc_count: 18000 attributes: - name: decision label: Decision type: select required: false description: Patent application decision status choices: - Accepted - Rejected - name: filing_date label: Filing Date type: date required: false description: Date the patent application was filed choices: [] prompt_context: |- Content types (by relevance): 1. Electricity (patent:electricity) — score: 1.72, 12 chunks * Relevant filters: - decision "Decision" (select: Accepted, Rejected) Other available attributes: - filing_date "Filing Date" (date: >=, <=) RULES: 1. Use null content_type when the query targets attributes without naming a topic area. ... OUTPUT FORMAT: {"content_type": "" or null, "attribute": [...]} prompt_version: t:a1b2c3d4.d:e5f6a7b8 summary: Strong match — single root Multi-root—Cross-schemaQuery: value: has_signal: true groups: - root: patent root_label: Patent Classification max_score: 1.72 content_types: - path: patent:electricity:h04 label: Electric Communication Technique root: patent score: 1.72 chunk_count: 8 doc_count: 12000 attributes: - name: decision label: Decision type: select required: false description: Patent application decision status choices: - Accepted - Rejected - name: filing_date label: Filing Date type: date required: false description: Date the patent application was filed choices: [] - path: patent:electricity:h01 label: Basic Electric Elements root: patent score: 0.91 chunk_count: 3 doc_count: 8500 attributes: - name: decision label: Decision type: select required: false description: Patent application decision status choices: - Accepted - Rejected - name: filing_date label: Filing Date type: date required: false description: Date the patent application was filed choices: [] - root: sic root_label: SIC Industry max_score: 0.45 content_types: - path: sic:manufacturing label: Manufacturing root: sic score: 0.45 chunk_count: 2 doc_count: 3200 attributes: - name: industry_code label: Industry Code type: text required: false description: SIC industry classification code choices: [] prompt_context: |- Content types (by relevance): 1. Electric Communication Technique (patent:electricity:h04) — score: 1.72, 8 chunks * 2. Manufacturing (sic:manufacturing) — score: 0.45, 2 chunks ... OUTPUT FORMAT: {"content_type": "" or null, "attribute": [...]} prompt_version: t:a1b2c3d4.d:e5f6a7b8 summary: Multi-root — cross-schema query LowConfidence—BelowThreshold: value: has_signal: false groups: - root: patent root_label: Patent Classification max_score: 0.42 content_types: - path: patent:electricity label: Electricity root: patent score: 0.42 chunk_count: 1 doc_count: 18000 attributes: - name: decision label: Decision type: select required: false description: Patent application decision status choices: - Accepted - Rejected - name: filing_date label: Filing Date type: date required: false description: Date the patent application was filed choices: [] prompt_context: >- No confident content type match — query may target metadata (dates, names, codes) rather than a specific domain. Content types (by relevance): 1. Electricity (patent:electricity) — score: 0.42, 1 chunks OUTPUT FORMAT: {"content_type": "" or null, "attribute": [...]} prompt_version: t:a1b2c3d4.d:e5f6a7b8 summary: Low confidence — below threshold description: >- has_signal is false when the top score is below the confidence threshold. Groups, attributes, and prompt_context are still returned — use scores to decide whether to apply filters. WithScopeCompletion(modelProvided): value: has_signal: true groups: - root: patent root_label: Patent Classification max_score: 1.85 content_types: - path: patent:electricity label: Electricity root: patent score: 1.85 chunk_count: 15 doc_count: 18000 attributes: - name: decision label: Decision type: select required: false description: Patent application decision status choices: - Accepted - Rejected - name: filing_date label: Filing Date type: date required: false description: Date the patent application was filed choices: [] prompt_context: |- Content types (by relevance): 1. Electricity (patent:electricity) — score: 1.85, 15 chunks * Relevant filters: - filing_date "Filing Date" (date: >=, <=) Other available attributes: - decision "Decision" (select: Accepted, Rejected) RULES: ... OUTPUT FORMAT: {"content_type": "" or null, "attribute": [...]} prompt_version: t:a1b2c3d4.d:e5f6a7b8 scope_completion: content_type: patent:electricity attribute: - filing_date:>=2023-01-01 - filing_date:<=2023-03-31 raw_output: >- {"content_type":"patent:electricity","attribute":["filing_date:>=2023-01-01","filing_date:<=2023-03-31"]} normalized: false warnings: [] summary: With scope_completion (model provided) description: >- When model is provided, scope_completion contains parsed filters. scope_completion.content_type and scope_completion.attribute map directly to the search API parameters. raw_output is the LLM's original response. prompt_context is always returned alongside for debugging or fallback. SchemaContext(noQuery): value: has_signal: false groups: - root: patent root_label: Patent Classification max_score: 0 content_types: - path: patent label: Patent root: patent score: 0 chunk_count: 0 doc_count: 20000 attributes: [] - path: patent:electricity label: Electricity root: patent score: 0 chunk_count: 0 doc_count: 18000 attributes: - name: decision label: Decision type: select required: false description: Patent application decision status choices: - Accepted - Rejected - name: filing_date label: Filing Date type: date required: false description: Date the patent application was filed choices: [] prompt_context: |- Available content type schemas: Patent Classification (patent): - Electricity (patent:electricity) Attributes: - Decision (select: Accepted, Rejected) on patent:electricity - Filing Date (date) on patent:electricity RULES: ... OUTPUT FORMAT: {"content_type": "" or null, "attribute": [...]} summary: Schema context (no query) description: >- No query → full CT catalog with attributes. groups contains all content types (score=0, chunk_count=0 since no query to rank). prompt_context contains the same catalog as LLM-ready text. description: Scored content types grouped by root. '400': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' description: Invalid request body. '401': content: application/json: schema: $ref: '#/components/schemas/APIV3ErrorResponse' examples: Unauthorized: value: id: null code: 401 error: unauthorized detail: >- Authentication credentials were not provided or are invalid. doc_url: https://developers.lighton.ai/errors#unauthorized description: Authentication credentials were not provided or are invalid '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 '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' security: - bearerAuth: [] components: schemas: FacetScopeRequest: description: Request body for POST /api/v3/content-types/scope. properties: query: anyOf: - maxLength: 2000 type: string - type: 'null' default: null description: >- Search query. Omit to get the full schema context for system prompts. title: Query max_results: default: 20 description: Max content types to return. maximum: 100 minimum: 1 title: Max Results type: integer threshold: default: 1.8 description: '[Beta] Score threshold for has_signal. Set to 0 to disable.' minimum: 0 title: Threshold type: number model: anyOf: - maxLength: 256 type: string - type: 'null' default: null description: >- Model technical name for LLM completion. When provided, the API calls the model with the prompt_context and returns a scope_completion with the parsed and normalized result. Omit to return prompt_context only. title: Model relevance_scoring: anyOf: - const: none type: string - type: 'null' default: null description: >- Controls the relevance scoring step. Omit (default) to retrieve and score content types by query relevance. "none": Skip retrieval scoring and return all content types (score=0). Useful with model for LLM completion over the full catalog. When 'none', max_results and threshold are ignored. title: Relevance Scoring title: FacetScopeRequest type: object FacetScopeResponse: properties: has_signal: title: Has Signal type: boolean groups: items: $ref: '#/components/schemas/RootGroup' title: Groups type: array prompt_context: anyOf: - type: string - type: 'null' default: null title: Prompt Context prompt_version: anyOf: - type: string - type: 'null' default: null title: Prompt Version scope_completion: anyOf: - $ref: '#/components/schemas/ScopeCompletion' - type: 'null' default: null required: - has_signal - groups title: FacetScopeResponse type: object 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 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. RootGroup: properties: root: title: Root type: string root_label: title: Root Label type: string max_score: title: Max Score type: number content_types: items: $ref: '#/components/schemas/ScoredContentType' title: Content Types type: array required: - root - root_label - max_score - content_types title: RootGroup type: object ScopeCompletion: description: Parsed and normalized LLM scope inference result. properties: content_type: anyOf: - type: string - type: 'null' default: null title: Content Type attribute: default: [] items: type: string title: Attribute type: array raw_output: default: '' title: Raw Output type: string normalized: default: false title: Normalized type: boolean warnings: default: [] items: type: string title: Warnings type: array title: ScopeCompletion type: object 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 ScoredContentType: properties: path: title: Path type: string label: title: Label type: string root: title: Root type: string score: title: Score type: number chunk_count: title: Chunk Count type: integer doc_count: title: Doc Count type: integer attributes: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' default: null title: Attributes required: - path - label - root - score - chunk_count - doc_count title: ScoredContentType type: object securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your auth token. ````