Scoping and Filtering
Refine your queries with field sets, type filters, and advanced options
Scoping and Filtering
Refine your search queries using field sets, type filters, and advanced query syntax to get precise results.
Field Sets
Control how much detail is returned using the field_set parameter:
| Field Set | Includes | Use Case |
|---|---|---|
basic | id, title, summary, gist, type | Quick lookups, citations |
content | basic + text | When you need the full content |
metadata | basic + tags, hypernyms, hyponyms | Categorization, filtering |
all | All available fields | Full context |
# Get basic fields (default)
curl "https://api.recurse.dev/search/?query=...&field_set=basic"
# Get full content
curl "https://api.recurse.dev/search/?query=...&field_set=content"
# Get semantic metadata
curl "https://api.recurse.dev/search/?query=...&field_set=metadata"Metadata Example
With field_set=metadata, results include semantic classification:
{
"id": "abc123...",
"title": "Model Training",
"metadata": {
"tags": ["training", "models", "optimization"],
"hypernyms": ["machine learning", "AI"],
"hyponyms": ["gradient descent", "backpropagation"]
}
}Frame Slots
Some frame types include structured slot data in a slots object:
{
"id": "claim123...",
"title": "Performance Claim",
"type": "claim",
"score": 0.85,
"slots": {
"confidence": "certain",
"strength": "strong"
},
"children": []
}Query Syntax
The search endpoint supports a powerful query syntax that combines natural language with structured filters.
Pure Semantic Search
A plain text query performs semantic search:
curl "https://api.recurse.dev/search/?query=best+practices+for+API+design"Type Filters
Filter by frame type using the type: prefix:
# Find only claims
curl "https://api.recurse.dev/search/?query=type:claim"
# Find only definitions
curl "https://api.recurse.dev/search/?query=type:definition"
# Find sections
curl "https://api.recurse.dev/search/?query=type:section"Combined Queries
Combine semantic search with type filters:
# Find claims about performance
curl "https://api.recurse.dev/search/?query=type:claim+performance+benchmarks"
# Find definitions of technical terms
curl "https://api.recurse.dev/search/?query=type:definition+machine+learning"Available Frame Types
| Type | Description | Example |
|---|---|---|
section | Document sections with headers | Chapter, heading |
claim | Assertions that can be verified | "X improves Y by 20%" |
definition | Explanations of terms/concepts | "RAG is..." |
example | Illustrative instances | Code samples, case studies |
method | Processes and procedures | Step-by-step guides |
supporting_evidence | Data backing claims | Statistics, citations |
ID-Based Lookup
Retrieve specific nodes by ID:
# Single ID
curl "https://api.recurse.dev/search/?query=id:abc123"
# Multiple IDs
curl "https://api.recurse.dev/search/?query=id:abc123,def456,ghi789"ID lookups bypass semantic search and return exact matches.
Hierarchical Search (Depth)
Control how deep to search in the document hierarchy:
# Flat results (default for most queries)
curl "https://api.recurse.dev/search/?query=...&depth=0"
# Include one level of children
curl "https://api.recurse.dev/search/?query=...&depth=1"
# Include full subtree
curl "https://api.recurse.dev/search/?query=...&depth=2"Use depth > 0 when you want to retrieve a section along with all its nested content.
Strict Mode
For high-precision use cases, enable strict mode to filter out uncertain matches:
curl "https://api.recurse.dev/search/?query=...&strict=true"In strict mode:
- Results with low confidence are filtered out
- Empty results are returned rather than uncertain matches
- Best for fact-checking and precise retrieval
Relevance Scoring
Every result includes a score field from 0 to 1:
| Score Range | Interpretation |
|---|---|
| 0.7 - 1.0 | High confidence match |
| 0.5 - 0.7 | Good match |
| 0.35 - 0.5 | Partial match |
| < 0.35 | Filtered out by default |
Response Metadata
The response includes metadata about how your query was processed:
{
"query": "semantic:API design",
"total_found": 15,
"returned_count": 5,
"search_time_ms": 145.2,
"filters_applied": ["semantic", "type"],
"cutoff_applied": "gap_detection"
}Advanced Examples
Find High-Confidence Claims
curl "https://api.recurse.dev/search/?query=type:claim+performance&strict=true&limit=5"Get Full Document Section with Children
curl "https://api.recurse.dev/search/?query=id:section123&depth=2&field_set=content"Search with Children
curl "https://api.recurse.dev/search/?query=machine+learning&depth=1&field_set=basic&limit=10"Note: For citation-style output with
citation_index, use the/writing/answerendpoint instead.
Best Practices
- Start broad, then filter: Begin with semantic search, add type filters to narrow down
- Use appropriate field sets: Request only the fields you need to reduce latency
- Enable strict mode for facts: When accuracy matters more than recall
- Use pagination for large result sets: Don't request more than you need