curl --request POST \
--url https://paradigm.lighton.ai/api/v3/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "authentication system JWT tokens"
}
'{
"results": [
{
"chunk_id": "550e8400-e29b-41d4-a716-446655440000",
"content": "The indemnifying party shall hold harmless and indemnify the other party...",
"score": 0.95,
"scores": {
"text": 0.91,
"vision": null,
"keyword": 0.43,
"multivector": 0.78,
"relevance": 0.95
},
"source": {
"file_id": 512,
"filename": "customer-nda.pdf",
"title": "Customer NDA — Nimbus Labs",
"mime_type": "pdf",
"size_bytes": 482113,
"page_start": 3,
"page_end": 4,
"total_pages": 12,
"tags": [
{
"id": 7,
"name": "confidential"
}
],
"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"
}
}
}
],
"external_metadata": null
},
"workspace": {
"id": 42,
"name": "Legal Team"
}
}
]
}Search document chunks
Embedding → hybrid vector search → optional reranking, returning ranked chunks with provenance. No LLM generation is performed.
Billing: 1 retrieval credit per request.
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.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 none, false to scoring_and_filtering.
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 results, or file_id
to target specific files. file_id cannot be combined with workspace_id or
tag_id. Filters that resolve to no authorized resources are rejected.
When no filters are provided, search runs across all documents authorized for the
API key.
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.
Modes:
text(default): hybrid text searchvision: VLM-embedded page image search
Images: set include_image=true to receive a base64-encoded page image with
each result. In text mode the image is fetched from the VisionChunk covering the
chunk’s start page (empty string if no vision index exists for that page).
Bounding boxes (PDF only): set include_bboxes=true to append a bboxes array to each
result, giving the merged rectangles of the chunk’s text on the source PDF (raw
PDF points, top-left origin with y extending downward) so you can overlay highlights without re-locating
the chunk. One rectangle per logical group; a chunk spanning two pages produces at
least one rectangle per page. Available for PDF documents in text mode only — returns an
empty list for non-PDF, vision-mode, or pre-v2.2.1 chunks. When include_bboxes=false
(default) the bboxes key is omitted.
curl --request POST \
--url https://paradigm.lighton.ai/api/v3/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "authentication system JWT tokens"
}
'{
"results": [
{
"chunk_id": "550e8400-e29b-41d4-a716-446655440000",
"content": "The indemnifying party shall hold harmless and indemnify the other party...",
"score": 0.95,
"scores": {
"text": 0.91,
"vision": null,
"keyword": 0.43,
"multivector": 0.78,
"relevance": 0.95
},
"source": {
"file_id": 512,
"filename": "customer-nda.pdf",
"title": "Customer NDA — Nimbus Labs",
"mime_type": "pdf",
"size_bytes": 482113,
"page_start": 3,
"page_end": 4,
"total_pages": 12,
"tags": [
{
"id": 7,
"name": "confidential"
}
],
"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"
}
}
}
],
"external_metadata": null
},
"workspace": {
"id": 42,
"name": "Legal Team"
}
}
]
}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 search query. Maximum 4000 characters.
4000Filter 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 return after reranking. Range: 1–100.
1 <= x <= 100Restrict 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.
"text": hybrid keyword + vector search. "vision": VLM-embedded page image search.
text- textvision- vision
text, vision 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- nonescoring_only- scoring_onlyscoring_and_filtering- scoring_and_filtering
none, scoring_only, scoring_and_filtering Deprecated — use relevance_scoring. true → relevance_scoring=none, false → relevance_scoring=scoring_and_filtering. Ignored when relevance_scoring is provided.
Append a base64-encoded page image to each result.
Append merged bounding boxes (in PDF points, top-left origin) to each result so callers can overlay chunk highlights on PDF pages. PDF documents in text mode only — non-PDF and vision-mode results always return an empty list. Omitted from the response entirely when false.
Response
Ranked search results. Empty array if no documents match.
Retrieved chunks, ordered by score descending.
Show child attributes
Show child attributes
Present only when a pipeline signal degrades. Absent in the happy path.
Show child attributes
Show child attributes
Scoring breakdown. Present only when explain=true and SEARCH_EXPLAIN_MODE is enabled.
Show child attributes
Show child attributes