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"
}
'

{
  "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"
              }
            }
          }
        ]
      }
    }
  ]
}

Files Processing

Retrieve document chunks

deprecated

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

retrieve

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"
}
'

{
  "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

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

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

Budget

Usage

System

Agents

Threads

Tools

Models

MCP

Sources

Artifacts

Agent

Files

Facets

Tags

Workspaces

Files Processing

Users

API Keys

User Groups

SCIM

Retrieve document chunks

Authorizations

Body

Response