Skip to main content
This tutorial uses POST /api/v3/content-types/scope. The full schema lives in the API reference.
Your app receives free-text queries, but your corpus has structured metadata: content types, dates, jurisdictions, statuses. Agentic bridges the gap — it infers the right content type and attribute filters from a natural-language query before searching, so semantic search runs on a narrowed, relevant subset instead of the entire corpus. Without Agentic, a query like “rejected electronics patents filed after 2023” runs semantic search across all 20,000 documents. With Agentic, the API first infers 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 model parameter and the API calls the LLM for you. Returns scope_completion with parsed, normalized filters ready to pass to search.
  • Prompt mode — omit model and the API returns prompt_context, a pre-built text block you feed to your own LLM.
Both paths produce the same output: 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. Pass content_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. The simplest integration — one call to infer scope, one call to search within it.
scope_completion.py
The response includes ranked content types with their attribute definitions and the parsed scope:
Extract 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 the model 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.
Why choose prompt mode:
  • 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
Send this prompt to any LLM (temperature 0, max 200 tokens). Parse the JSON response and pass content_type and attribute to your search call, just like with completion mode:
Here’s a representative example of what prompt_context looks like for a patent corpus:
The sections are generated dynamically from your schema:
  • 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

Omit query 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

The groups 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 in attributes. Use these to build dynamic filter UIs, validate user input, or understand what scope_completion.attribute refers to.
Attribute types: 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.
Same 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’s score 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.