Ask a question over your documents

curl --request POST \
  --url https://api.lighton.ai/api/v3/ask \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "max_results": 10,
  "workspace_id": [
    123
  ],
  "tag_id": [
    123
  ],
  "file_id": [
    123
  ],
  "stream": false,
  "model": "mistral-large-latest"
}
'

{
  "results": [
    {
      "chunk_id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "JWT tokens are signed using RS256 and expire after 1 hour.",
      "score": {
        "retrieval": 0.92,
        "reranking": 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": [],
        "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

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 with results and answer.
stream=true: returns Server-Sent Events: event: sources (retrieved chunks), event: token (answer tokens), event: done (stream complete), or event: error (generation failure).

Model: defaults to mistral-large-latest (flagship, best answer quality). Pass model=alfred-ft5 for the lighter, faster LightOn fine-tune. Only these two models are supported; any other value returns 422.

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 (422).

Billing: 1 search-with-generation credit per request.

POST

api

ask

Ask a question over your documents

curl --request POST \
  --url https://api.lighton.ai/api/v3/ask \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "max_results": 10,
  "workspace_id": [
    123
  ],
  "tag_id": [
    123
  ],
  "file_id": [
    123
  ],
  "stream": false,
  "model": "mistral-large-latest"
}
'

{
  "results": [
    {
      "chunk_id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "JWT tokens are signed using RS256 and expire after 1 hour.",
      "score": {
        "retrieval": 0.92,
        "reranking": 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": [],
        "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

Authorization

string

header

required

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

Body

query

string

required

Natural-language question. Maximum 1500 characters.

Maximum string length: 1500

max_results

integer

default:10

Maximum number of chunks to retrieve for context. Range: 1–50.

Required range: 1 <= x <= 50

workspace_id

integer[]

Restrict search to these workspace IDs. Cannot combine with file_id.

tag_id

integer[]

Restrict to documents carrying any of these tag IDs (OR). Cannot combine with file_id.

file_id

integer[]

Restrict to specific file IDs. Cannot combine with workspace_id or tag_id.

stream

boolean

default:false

When true, response is streamed as Server-Sent Events.

model

enum<string>

default:mistral-large-latest

LLM used for answer generation. Allowed values:

mistral-large-latest: Mistral Large 2, flagship general-purpose model. Best answer quality (default).
alfred-ft5: Alfred FT5, LightOn fine-tuned model, lighter and faster for straightforward questions.

mistral-large-latest - mistral-large-latest
alfred-ft5 - alfred-ft5

Available options:

mistral-large-latest,

alfred-ft5

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).

results

object[]

required

Ranked search results used as context.

Show child attributes

answer

string

required

LLM-generated answer grounded in the retrieved results.

API Reference Extract structured data from a document

⌘I

Documentation Index

Authorizations

Body

Response