curl --request POST \
--url https://paradigm.lighton.ai/api/v3/content-types/scope \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "rejected electronics patents"
}
'{
"has_signal": true,
"groups": [
{
"root": "patent",
"root_label": "Patent Classification",
"max_score": 1.72,
"content_types": [
{
"path": "patent:electricity",
"label": "Electricity",
"root": "patent",
"score": 1.72,
"chunk_count": 12,
"doc_count": 18000,
"attributes": [
{
"name": "decision",
"label": "Decision",
"type": "select",
"required": false,
"description": "Patent application decision status",
"choices": [
"Accepted",
"Rejected"
]
},
{
"name": "filing_date",
"label": "Filing Date",
"type": "date",
"required": false,
"description": "Date the patent application was filed",
"choices": []
}
]
}
]
}
],
"prompt_context": "Content types (by relevance):\n 1. Electricity (patent:electricity) — score: 1.72, 12 chunks *\n\nRelevant filters:\n - decision \"Decision\" (select: Accepted, Rejected)\n\nOther available attributes:\n - filing_date \"Filing Date\" (date: >=, <=)\n\nRULES:\n 1. Use null content_type when the query targets attributes without naming a topic area.\n ...\n\nOUTPUT FORMAT:\n {\"content_type\": \"<path>\" or null, \"attribute\": [...]}",
"prompt_version": "t:a1b2c3d4.d:e5f6a7b8"
}Resolve search scope
Resolves content type and attribute filters from a natural-language query.
Call this before /search, /ask, or /files to narrow results by domain.
Pass the inferred content_type and attribute directly to those endpoints.
Returns ranked content types grouped by root schema, each with a relevance score and the attribute definitions available for filtering.
Scores and decision signal
Each content type in the response includes a score (relevance to your query).
Use scores to decide how to scope your search — higher means stronger match.
has_signal is a convenience shortcut: it’s true when the top score meets a
default confidence threshold. For custom logic, use score directly and apply
your own threshold via the threshold request parameter.
Three modes
1. Prompt mode (default) — returns prompt_context, a self-contained LLM-ready
text block. Feed it to any LLM alongside the user query to infer content_type
and attribute filters. The prompt includes ranked content types, attribute
definitions with filter syntax, inference rules, date ranges, and few-shot examples.
2. Completion mode — pass model (technical name) and the API calls the LLM
for you. Returns scope_completion with parsed, normalized filters:
- Label-to-name mapping (e.g. “Filing Date” →
filing_date) - Syntax validation against the attribute schema
- Structured JSON output via guided decoding
warningsfor any normalization applied or issues detected- If the LLM call fails,
scope_completionis still returned withwarningsexplaining the failure — the rest of the response remains usable.
3. Catalog + completion mode — set relevance_scoring: "none" with a query
and model to get the full content type catalog AND an LLM-inferred
scope_completion. Useful when you want the LLM to choose from ALL content types
without retrieval pre-filtering. max_results and threshold are ignored.
Response fields
| Field | Description |
|---|---|
score | Relevance score. Higher = better match. Comparable across requests. |
max_score | Highest score in a root group. Compare roots without iterating. |
chunk_count | Retrieval chunks matching this CT. More chunks = broader evidence. |
doc_count | Total corpus documents classified under this CT. |
prompt_context | LLM-ready prompt text. Pass to your LLM as-is. |
prompt_version | Fingerprint (t:<hex>.d:<hex>) for eval reproducibility. |
scope_completion | Parsed LLM output (only when model is provided). |
Schema context mode
Omit query to get the full content type catalog — useful for system prompts,
tool descriptions, or schema exploration. groups contains all content types with
their attributes (score=0, chunk_count=0 since there is no query to rank against).
prompt_context contains the same catalog as LLM-ready text.
Integration notes
- Content type paths use
:as separator (e.g.patent:electricity:h04). - Attribute filter syntax is documented in
prompt_contextper attribute type. Date ranges use>=/<=operators (e.g.filing_date:>=2023-01-01). - Writing meaningful attribute descriptions (especially for person-name and
code/identifier fields) improves the quality of
prompt_contexthints.
curl --request POST \
--url https://paradigm.lighton.ai/api/v3/content-types/scope \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "rejected electronics patents"
}
'{
"has_signal": true,
"groups": [
{
"root": "patent",
"root_label": "Patent Classification",
"max_score": 1.72,
"content_types": [
{
"path": "patent:electricity",
"label": "Electricity",
"root": "patent",
"score": 1.72,
"chunk_count": 12,
"doc_count": 18000,
"attributes": [
{
"name": "decision",
"label": "Decision",
"type": "select",
"required": false,
"description": "Patent application decision status",
"choices": [
"Accepted",
"Rejected"
]
},
{
"name": "filing_date",
"label": "Filing Date",
"type": "date",
"required": false,
"description": "Date the patent application was filed",
"choices": []
}
]
}
]
}
],
"prompt_context": "Content types (by relevance):\n 1. Electricity (patent:electricity) — score: 1.72, 12 chunks *\n\nRelevant filters:\n - decision \"Decision\" (select: Accepted, Rejected)\n\nOther available attributes:\n - filing_date \"Filing Date\" (date: >=, <=)\n\nRULES:\n 1. Use null content_type when the query targets attributes without naming a topic area.\n ...\n\nOUTPUT FORMAT:\n {\"content_type\": \"<path>\" or null, \"attribute\": [...]}",
"prompt_version": "t:a1b2c3d4.d:e5f6a7b8"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Request body for POST /api/v3/content-types/scope.
Search query. Omit to get the full schema context for system prompts.
2000Max content types to return.
1 <= x <= 100[Beta] Score threshold for has_signal. Set to 0 to disable.
x >= 0Model technical name for LLM completion. When provided, the API calls the model with the prompt_context and returns a scope_completion with the parsed and normalized result. Omit to return prompt_context only.
256Controls the relevance scoring step. Omit (default) to retrieve and score content types by query relevance. "none": Skip retrieval scoring and return all content types (score=0). Useful with model for LLM completion over the full catalog. When 'none', max_results and threshold are ignored.
"none"Response
Scored content types grouped by root.