LIlighton
Ask

Ask a question over your documents

Changed on

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: omit model to use the default model configured for your organization. To name one explicitly, pass any technical name from GET /api/v3/instance/models — that endpoint lists exactly what this endpoint accepts: the models your deployment offers publicly, your organization's default, and any model your organization registered itself (custom-{company_id}-{uuid}). Any other value is rejected.

Structured output: pass response_format with a JSON Schema object to constrain the LLM answer to valid JSON matching your schema. The schema must have type: "object" and properties. When set, the answer field contains a JSON string conforming to the schema. Works with both sync and streaming modes. Omit for free-text answers (default).

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.

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 a retrieval or scoring signal is temporarily unavailable, results are still returned — in retrieval order when the degraded signal is the reranker — and each result item includes a warnings array. Each warning has a code matching the degraded scores key (relevance, multivector, vision) and a reason classifying the failure: model_not_found, embed_failed, timeout, service_error, or unknown. A degraded signal lowers ranking quality and leaves its scores entry null. The warnings key is absent from result items when all pipeline steps succeed.

Billing: 1 search-with-generation credit per request.

post/api/v3/ask

Request

  • Base URL
    https://api.lighton.ai
  • URL
    https://api.lighton.ai/api/v3/ask
  • Auth
    HTTP bearer

Request body

content_typestring[]

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).

attributestring[]

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:<value / name:<=value (lt/lte), name:prefix* (starts with, case-insensitive), name:*text* (contains, case-insensitive), name:a|b (OR). Smart dates: filing_date:2023 (year), filing_date:2023-06 (month). Type-aware: booleans (true/false), multi-select (membership check). Scoped: content_type(legal:compliance).regulation:AML.

querystring required

Natural-language question. Maximum 1500 characters.

max_resultsinteger

Maximum number of chunks to retrieve for context. Range: 1–50.

workspace_idinteger[]

Restrict search to these workspace IDs. Cannot combine with file_id.

tag_idinteger[]

Restrict to documents carrying any of these tag IDs (OR). Cannot combine with file_id.

file_idinteger[]

Restrict to specific file IDs. Cannot combine with workspace_id or tag_id.

relevance_scoring'none' | 'scoring_only' | 'scoring_and_filtering'
  • none - none
  • scoring_only - scoring_only
  • scoring_and_filtering - scoring_and_filtering
streamboolean

When true, response is streamed as Server-Sent Events.

modelstring nullable

LLM used for answer generation. Omit to use the default model configured for your organization. Accepted values are the technical names your deployment offers publicly, your organization's own default, and any model your organization registered itself (e.g. custom-{company_id}-{uuid}). Call GET /api/v3/instance/models for the current list — every model it returns can be named here.

response_formatunknown

Response

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).

answerstring required

LLM-generated answer grounded in the retrieved results.

Changes

  • 63ecbc61b6a9Revision changes
    • info

      added the new optional request property (media type: application/json)

    • info

      added the new optional request property (media type: application/x-www-form-urlencoded)

    • info

      added the new optional request property (media type: multipart/form-data)

    • info

      the request property became nullable (media type: application/json)

    • info

      the request property became nullable (media type: application/x-www-form-urlencoded)

    • info

      the request property became nullable (media type: multipart/form-data)

    • info

      the request property default value mistral-large-latest was removed (media type: application/json)

    • info

      the request property default value mistral-large-latest was removed (media type: application/x-www-form-urlencoded)

    • info

      the request property default value mistral-large-latest was removed (media type: multipart/form-data)

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status