curl --request POST \
--url https://api.lighton.ai/api/v3/ask \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "How are JWT tokens signed?",
"max_results": 5,
"workspace_id": [
42
]
}
'{
"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)."
}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 withresultsandanswer.stream=true: returns Server-Sent Events —event: sources(retrieved chunks),event: token(answer tokens),event: done(stream complete), orevent: 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.
curl --request POST \
--url https://api.lighton.ai/api/v3/ask \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "How are JWT tokens signed?",
"max_results": 5,
"workspace_id": [
42
]
}
'{
"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)."
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
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
Natural-language question. Maximum 1500 characters.
1500Filter 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).
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.
Maximum number of chunks to retrieve for context. Range: 1–50.
1 <= x <= 50Restrict search to these workspace IDs. Cannot combine with file_id.
Restrict to documents carrying any of these tag IDs (OR). Cannot combine with file_id.
Restrict to specific file IDs. Cannot combine with workspace_id or tag_id.
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- nonescoring_only- scoring_onlyscoring_and_filtering- scoring_and_filtering
none, scoring_only, scoring_and_filtering When true, response is streamed as Server-Sent Events.
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.
JSON Schema object for structured output. When provided, the LLM answer is constrained to match this schema. Must have type: "object" and properties.
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).