Skip to main content
POST
/
api
/
v3
/
retrieve
curl --request POST \
  --url https://paradigm-preprod.lighton.ai/api/v3/retrieve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "authentication system JWT tokens"
}
'
{
  "results": [
    {
      "chunk": {
        "id": 1024,
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "content_id": "content_id_550e8400-e29b-41d4-a716-446655440000",
        "text": "JWT tokens are signed using RS256 and expire after 1 hour.",
        "chunk_type": "text",
        "metadata": {
          "pages": "3-4",
          "total_pages": "12"
        },
        "created_at": "2025-11-01T09:00:00Z",
        "updated_at": "2025-11-01T09:00:00Z"
      },
      "scoring": {
        "score": 0.92,
        "distance": 0.08,
        "lexical_score": 0.74,
        "certainty": 0.95
      },
      "workspace": {
        "id": 42,
        "name": "Engineering Docs",
        "workspace_type": "custom"
      },
      "document": {
        "id": 512,
        "name": "auth-system.pdf",
        "file_type": "pdf",
        "status": "embedded",
        "total_pages": 12,
        "uploaded_at": "2025-10-30T08:00:00Z",
        "title": "Authentication System Design",
        "tags": [
          {
            "id": 7,
            "name": "security",
            "auto_assigned": false
          }
        ],
        "external_metadata": null
      }
    }
  ]
}

Authorizations

Authorization
string
header
required

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

Body

query
string
required

Natural-language search query.

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 chunks retrieved from the vector store before reranking. Range: 1–100.

Required range: 1 <= x <= 100
top_n
integer
default:10

Number of chunks returned after filtering. Range: 1–50. Must be ≤ top_k.

Required range: 1 <= x <= 50
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).

skip_rerank
boolean
default:false

Skip reranking. Useful to isolate retrieval quality.

include_image
boolean
default:false

Include base64-encoded page image in each result.

Response

Chunks retrieved successfully. Empty array if no documents match.

results
object[]
required

Retrieved chunks with context