content_type: patent:electricity and attribute: decision_status:REJECTED, filing_date:>=2023-01-01, then searches only the 5,409 matching documents.
The endpoint supports two modes:
- Completion mode — pass a
modelparameter and the API calls the LLM for you. Returnsscope_completionwith parsed, normalized filters ready to pass to search. - Prompt mode — omit
modeland the API returnsprompt_context, a pre-built text block you feed to your own LLM.
content_type and attribute filters that map directly to the search API parameters.
When you don’t need scope inference
If your app already knows the right filters (e.g. the user picks “NDA” from a dropdown), skip the scope endpoint. Passcontent_type and attribute directly to POST /api/v3/search, POST /api/v3/ask, or GET /api/v3/files. See Filtering documents by metadata for the full syntax.
Quickstart: scope then search
The simplest integration — one call to infer scope, one call to search within it.scope_completion.py
content_type and attribute from scope_completion and pass them to your search call:
scope_then_search.py
scope_completion.content_type and scope_completion.attribute map directly to the search API parameters — no transformation needed. If the LLM call fails, scope_completion is still returned with a warnings array explaining the failure, and the rest of the response (scores, groups, attributes) remains usable.
For the full attribute filter syntax (operators, OR logic, date shortcuts), see Filtering documents by metadata.
Prompt mode: bring your own LLM
Completion mode handles everything in one call, but it uses the auto-generated prompt as-is. If you need more control, use prompt mode: omit themodel parameter and the API returns prompt_context instead of calling an LLM.
Without
model, the scope endpoint does not return scope_completion. You get prompt_context, groups, and scores, but you need your own LLM call to produce the content_type and attribute filters.- Add domain-specific rules that the auto-generated prompt doesn’t know about (e.g. “‘Project Aurora’ is our internal name for renewable energy patents”)
- Add few-shot examples that teach the LLM patterns specific to your data
- Post-process the LLM output with validation or normalization before searching
- Use a model not available through the completion mode
Step 1: Get the prompt context
scope_prompt.py
Step 2: Call your LLM and search
Send this prompt to any LLM (temperature 0, max 200 tokens). Parse the JSON response and passcontent_type and attribute to your search call, just like with completion mode:
What's inside prompt_context
What's inside prompt_context
Here’s a representative example of what The sections are generated dynamically from your schema:
prompt_context looks like for a patent corpus:- Content types — ranked by query relevance. The
*marks the top match. - Relevant filters — attributes the API detected as related to the query (e.g., date keywords triggered
filing_date). Shows filter syntax per type. - Other available attributes — remaining attributes you can filter on.
- Rules — inference guidelines for the LLM. Adapted to your schema (e.g., date rules only appear if you have date attributes).
- Date guide — period interpretation. Helps the LLM translate “Q1” into concrete dates.
- Examples — few-shot demonstrations generated from your actual content types and attributes.
- Output format — the JSON schema the LLM should respond with.
Schema context: pre-load the catalog
Omitquery to get the full content type catalog — useful for system prompts, tool descriptions, or schema exploration. If you have few content types, this avoids scoring latency.
groups contains all your content types with their attributes (score=0.0 and chunk_count=0 since there’s no query to rank against). doc_count reflects corpus size. prompt_context contains the same catalog formatted as text for LLM consumption.
Understanding the response
Content types and scoring
Thegroups array contains content types grouped by root schema (e.g., “Patent Classification” and “SIC Industry” are separate roots). Each group represents an independent taxonomy.
score— relevance to the query. Higher = stronger match. Comparable across requests.chunk_count— how many retrieval chunks matched this content type for this specific query. Measures evidence strength.doc_count— total documents classified under this content type in your corpus. Measures coverage.max_score— highest score in a root group. Compare roots at a glance without iterating content types.
Attribute definitions
Each content type includes its attribute definitions inattributes. Use these to build dynamic filter UIs, validate user input, or understand what scope_completion.attribute refers to.
date, select, multi-select, text, number, boolean, rich-text. For select and multi-select, choices lists the valid values. You never need to parse prompt_context to know what attributes exist — they’re here as structured data.
Prompt version (evaluation)
prompt_version is a fingerprint in the format t:<hex>.d:<hex>:
t:hashes the prompt template (rules, patterns, syntax). Changes when the platform updates its inference logic.d:hashes the per-request data (scored paths, attribute definitions). Changes when your corpus or schema changes.
prompt_version = same prompt was generated. Useful for A/B testing LLMs on the same prompt, or detecting when a platform update changed the prompt your users receive.
Scoring and confidence
Scores are the primary signal for deciding whether to scope your search. The top content type’sscore tells you how relevant it is to the query.
has_signal is a convenience shortcut — it’s true when the top score meets a default confidence threshold. For custom logic, compare groups[].content_types[].score against your own threshold, or pass the threshold request parameter to adjust the cutoff.
When the top score is low, groups and attributes are still returned — you can present them to users as suggestions or apply them conditionally based on your own rules.
When Agentic adds the most value
Agentic delivers the most value on queries that combine free text with structured constraints: dates, statuses, person names, classification codes. These represent roughly 65% of real-world queries and are exactly where semantic search alone falls short.