Retrieve document chunks

Deprecated: Use the v3 search endpoint instead.

Invoke the document retrieval pipeline (embedding + hybrid vector search + reranking) and return matched document chunks.

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. 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 relevance_scoring for the default; send none to skip scoring. skip_rerank is deprecated — true maps to relevance_scoring=none, false to scoring_and_filtering. relevance_scoring wins if both are sent.

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 retrieval to specific workspaces or tags, or use file_id to target specific files. file_id cannot be combined with workspace_id or tag_id. A 403 is returned if any provided filter resolves to no authorized resources. When no filters are provided, retrieval runs across all authorized documents.

Public datasets: a public dataset workspace must be the only workspace in the request — combining it with any other workspace_id, file_id, or tag_id returns 400. Public datasets are reachable only through a workspace-scoped API key whose scope includes the workspace, and only for companies allowed to access them; otherwise the result is empty.

Facet filtering: use content_type and/or attribute to narrow retrieval by document metadata. These can be combined with workspace/tag scoping. Content type uses colon-separated paths (e.g. legal:contract:nda). Attributes support operators, OR, and content-type scoping.

Modes:

• text (default): hybrid text search
• vision: image-based search

Explain mode: set explain=true to receive a per-chunk scoring breakdown in the response (raw scores, normalized scores, fusion weights, filter stats, timing). Requires the SEARCH_EXPLAIN_MODE feature flag to be enabled.

POST /api/v3/retrieve

cURL

TextMode—ScopedToWorkspace

curl --request POST \
  --url https://paradigm.lighton.ai/api/v3/retrieve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "authentication system JWT tokens"
}
'

200

TextModeResult—WithRerankingAndFacetScoping

{
  "query": "indemnification clause",
  "retrieve_params": {
    "mode": "text",
    "top_k": 20,
    "relevance_scoring": "scoring_and_filtering",
    "skip_rerank": false,
    "include_image": false,
    "explain": false
  },
  "scoping_params": {
    "file_id": [],
    "tag_id": [],
    "workspace_id": [
      42
    ],
    "content_type": [
      "legal:contract"
    ],
    "attribute": [
      "jurisdiction:FR"
    ]
  },
  "results": [
    {
      "chunk": {
        "id": 1024,
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "content_id": "content_id_550e8400-e29b-41d4-a716-446655440000",
        "text": "The indemnifying party shall hold harmless and indemnify the other party...",
        "chunk_type": "text",
        "metadata": {
          "pages": "3-4",
          "total_pages": 12,
          "title": "Customer NDA — Nimbus Labs",
          "source": "customer-nda.pdf",
          "parser": "v2.2.1",
          "folder_name": "legal/customers",
          "coords": "3,72.0,120.0,450.0,18.0;4,72.0,80.0,450.0,18.0",
          "previous": "550e8400-e29b-41d4-a716-446655440002",
          "next": "550e8400-e29b-41d4-a716-446655440004",
          "overlapping": "",
          "token_length": 412
        },
        "created_at": "2025-11-01T09:00:00Z",
        "updated_at": "2025-11-01T09:00:00Z"
      },
      "scoring": {
        "score": 0.95,
        "scores": {
          "text": 0.92,
          "vision": 0.12,
          "keyword": 0.74,
          "multivector": 0.81,
          "relevance": 0.95
        }
      },
      "workspace": {
        "id": 42,
        "name": "Legal Team",
        "workspace_type": "custom"
      },
      "document": {
        "id": 512,
        "name": "customer-nda.pdf",
        "file_type": "pdf",
        "status": "embedded",
        "total_pages": 12,
        "uploaded_at": "2025-10-30T08:00:00Z",
        "title": "Customer NDA — Nimbus Labs",
        "tags": [
          {
            "id": 7,
            "name": "confidential",
            "auto_assigned": true
          }
        ],
        "external_metadata": {
          "external_id": "legal-doc-456789",
          "doc_type": "nda",
          "additional_metadata": {
            "external_url": "https://contracts.example.com/legal/customer-nda"
          }
        },
        "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"
              }
            }
          }
        ]
      }
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

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

query · string · required

Natural-language search query. Maximum 1500 characters.

Maximum string length: 1500

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.

mode · enum<string> · default: text

Retrieval pipeline: "text" (hybrid search on DocumentChunk) or "vision" (image-based on VisionChunk).

• text - text
• vision - vision

Available options: text, vision

top_k · integer · default: 20

Number of best candidates to score and return. Relevance scoring evaluates all top_k candidates from retrieval; scoring_and_filtering then keeps only those above the quality threshold. Range: 1–100.

Required range: 1 <= x <= 100

workspace_id · integer[]

Scope retrieval to specific workspace IDs (authorized only).

file_id · integer[]

Scope retrieval to specific file IDs (authorized only).

tag_id · integer[]

Scope retrieval to documents with any of these tag IDs (company-scoped).

relevance_scoring · enum<string>

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 - none
• scoring_only - scoring_only
• scoring_and_filtering - scoring_and_filtering

Available options: none, scoring_only, scoring_and_filtering

skip_rerank · boolean

Deprecated — use relevance_scoring. true → relevance_scoring=none, false → relevance_scoring=scoring_and_filtering. Ignored when relevance_scoring is provided.

include_image · boolean · default: false

Include base64-encoded page image in each result.

include_details · boolean · default: false

Expand document metadata in results. When true, content types include breadcrumb, code, and attribute definitions (type, required, choices).

Response

200

application/json

Chunks retrieved successfully. Empty array if no documents match.

query · string · required

The search query that was executed.

retrieve_params · object · required

Retrieval parameters used (including defaults).

Show child attributes

scoping_params · object · required

Scoping parameters used to narrow retrieval.

Show child attributes

results · object[] · required

Retrieved chunks with context, ordered by score descending.

Show child attributes

warnings · object[]

Present only when a pipeline signal degrades. Absent in the happy path.

Show child attributes