---
title: "Ask a question over your documents"
method: POST
path: "/api/v3/ask"
tags: ["Ask"]
---

# Ask a question over your documents

`POST /api/v3/ask`

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.

## Request body

- AskRequest — 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
  - `content_type` string[] — 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` string[] — 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`.
  - `query` string, required — Natural-language question. Maximum 1500 characters.
  - `max_results` integer — Maximum number of chunks to retrieve for context. Range: 1–50.
  - `workspace_id` integer[] — Restrict search to these workspace IDs. Cannot combine with file_id.
  - `tag_id` integer[] — Restrict to documents carrying any of these tag IDs (OR). Cannot combine with file_id.
  - `file_id` integer[] — 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
  - `stream` boolean — When true, response is streamed as Server-Sent Events.
  - `model` string — 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.

## Response `200`

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

- AskResponse
  - `results` AskResultItem[], required — Retrieved chunks used as context, ordered by relevance score descending.
    - `chunk_id` string, uuid, required — Chunk UUID.
    - `content` string, nullable, required — Chunk text content. Null for vision-mode chunks.
    - `score` number, double, required — 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` SearchScores, required
      - `text` number, double, nullable, required — Semantic text similarity (0–1, higher is better). Null in vision mode.
      - `vision` number, double, nullable, required — Vision page similarity (0–1, higher is better). Null when the document has no vision index.
      - `keyword` number, double, nullable, required — Keyword match score (higher is better, no fixed upper bound). Null in vision mode.
      - `multivector` number, double, nullable, required — Token-level similarity score (higher is better, no fixed upper bound). Null when multi-vector scoring is disabled.
      - `relevance` number, double, nullable, required — 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.
    - `image` SearchImage
      - `b64_content` string, required — Base64-encoded page image. Empty string when no vision index exists for the page.
    - `source` SearchSource, required
      - `file_id` integer, required — File ID.
      - `filename` string, required — Original filename.
      - `title` string, nullable, required — Document title.
      - `mime_type` string, nullable, required — File type (e.g. pdf, docx).
      - `size_bytes` integer, nullable, required — File size in bytes.
      - `page_start` integer, nullable, required — Start page of the chunk (1-indexed).
      - `page_end` integer, nullable, required — End page of the chunk (1-indexed).
      - `total_pages` integer, required — Total pages in the document.
      - `tags` SearchTag[], required — Tags associated with the document.
        - `id` integer, required — Tag ID.
        - `name` string, required — Tag name.
      - `content_types` object[] — Facet content type classifications and attribute values.
      - `external_metadata` SearchExternalMetadata, required
        - `external_id` string, required — ID of the document in the external system.
        - `external_url` string, nullable, required — Deep-link back to the document in the source system. Null if not provided.
        - `additional_metadata` object, required — Freeform connector metadata. external_url is lifted to its own field and excluded here.
    - `workspace` SearchWorkspace, required
      - `id` integer, required — Workspace ID.
      - `name` string, required — Workspace name.
    - `bboxes` SearchBbox[] — 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.
      - `page_number` integer, required — 1-indexed page the rectangle sits on.
      - `x` number, double, required — Left edge in PDF points, top-left origin.
      - `y` number, double, required — Top edge in PDF points, top-left origin (y extends downward).
      - `width` number, double, required — Width in PDF points.
      - `height` number, double, required — Height in PDF points.
      - `unit` string, required — Coordinate unit. Always "pdf_point" in v1.
      - `origin` string, required — Coordinate origin. Always "top_left" in v1.
    - `warnings` SearchWarning[] — Present only when a pipeline signal degrades. Absent in the happy path.
      - `code` string, required — Signal name from the scores object that degraded (e.g. 'relevance').
      - `reason` string — Machine-readable failure reason (model_not_found, timeout, service_error, unknown).
  - `answer` string, required — LLM-generated answer grounded in the retrieved results.

## Other responses

- `400` — Request body is not parsable JSON.
- `401` — Missing or invalid API key.
- `403` — API key has no authorized resources matching the provided filters.
- `404` — 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` — Field validation failure.
- `429` — Rate limit exceeded.
- `500` — Unexpected server error.
- `503` — Model temporarily unavailable.
- `504` — Model timeout.

---

[API](https://skmtc.dev/lighton/apis/lighton-api.md) · [All operations](https://skmtc.dev/lighton/apis/lighton-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lighton/lighton-api/revisions/86c57e94ef15/schema)