Search and Filter
Fetch, filter, and search your content with practical code examples. This guide covers six query patterns — from listing resources to semantic search — ready to copy into your JavaScript or Python application.
Prerequisites
Before you start:
- A Flux API with at least one connected folder. See Build Flux APIs.
- API credentials (if authentication is enabled). See Manage Roles and API Keys.
- Your environment key (e.g.,
7c9h4pwu) from the Flux API settings.
Python SDK Installation
For Python examples, install the official SDK:
pip install foxnose-sdk
Your API Endpoint
Flux API URLs follow this pattern:
https://{environment_key}.fxns.io/{api_prefix}/{folder_path}
For example, if your environment key is 7c9h4pwu, your API prefix is content, and you have a folder with alias articles:
https://7c9h4pwu.fxns.io/content/articles
Fetch All Resources
The simplest request — get all resources from a folder:
const API_URL = 'https://7c9h4pwu.fxns.io/content/articles';
async function listArticles() {
const response = await fetch(API_URL);
const data = await response.json();
console.log(`Found ${data.results.length} articles`);
for (const article of data.results) {
console.log(`- ${article.data.title} (${article._sys.key})`);
}
return data.results;
}
listArticles();
Response structure:
{
"limit": 100,
"next": null,
"previous": null,
"results": [
{
"_sys": {
"key": "hG9tL4nRmXwP",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"folder": "articles"
},
"data": {
"title": "Getting Started with FoxNose",
"body": "Learn how to build content APIs..."
}
}
]
}
Add Authentication
If your Flux API requires authentication, the SDK handles it automatically:
const API_URL = 'https://7c9h4pwu.fxns.io/content/articles';
const PUBLIC_KEY = 'your-public-key';
const SECRET_KEY = 'your-secret-key';
async function listArticlesAuth() {
const response = await fetch(API_URL, {
headers: {
'Authorization': `Simple ${PUBLIC_KEY}:${SECRET_KEY}`
}
});
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
return response.json();
}
Simple authentication is for development only. Use Secure authentication with signatures in production.
Filter by Field Values
Filter resources using query parameters or the search endpoint:
// Filter by field value
const url = new URL('https://7c9h4pwu.fxns.io/content/articles');
url.searchParams.set('where__status__eq', 'published');
url.searchParams.set('where__category__in', 'tech,science');
url.searchParams.set('limit', '10');
const response = await fetch(url);
const data = await response.json();
Common filter operators:
| Operator | Example | Description |
|---|---|---|
eq | where__status__eq=published | Equals |
in | where__tags__in=ai,ml | Value in list |
gt, gte, lt, lte | where__price__gte=100 | Comparisons |
contains | where__title__icontains=guide | Substring (case-insensitive) |
See List Resources for all operators.
Search by Meaning (Vector Search)
Find content similar in meaning to a natural language query. This requires at least one field with vectorization enabled in your schema.
const url = new URL('https://7c9h4pwu.fxns.io/content/articles');
url.searchParams.set('search_mode', 'vector');
url.searchParams.set('vector_search__query', 'how to build AI applications');
url.searchParams.set('vector_search__top_k', '5');
url.searchParams.set('vector_search__similarity_threshold', '0.7');
const response = await fetch(url);
const data = await response.json();
// Results are ranked by semantic similarity
for (const result of data.results) {
console.log(`${result.data.title}`);
}
Search modes:
| Mode | Use Case |
|---|---|
text | Default. Keyword-based full-text search |
vector | Pure semantic search based on meaning |
hybrid | Combines filters + semantic ranking |
Handle Large Result Sets
Fetch paginated results when you have more content than fits in one response:
async function fetchAllArticles() {
const allResults = [];
let url = 'https://7c9h4pwu.fxns.io/content/articles?limit=50';
while (url) {
const response = await fetch(url);
const data = await response.json();
allResults.push(...data.results);
url = data.next; // null when no more pages
}
return allResults;
}
Complete Example: Search with Filters
Combine semantic search, filters, and error handling:
const API_BASE = 'https://7c9h4pwu.fxns.io/content';
async function search(query, options = {}) {
const url = new URL(`${API_BASE}/articles`);
// Use vector search for natural language queries
if (query) {
url.searchParams.set('search_mode', 'vector');
url.searchParams.set('vector_search__query', query);
url.searchParams.set('vector_search__top_k', options.limit || 10);
}
// Apply filters
if (options.category) {
url.searchParams.set('where__category__eq', options.category);
}
if (options.status) {
url.searchParams.set('where__status__eq', options.status);
}
const response = await fetch(url);
if (!response.ok) {
const error = await response.json();
throw new Error(error.message || 'Search failed');
}
return response.json();
}
// Usage
const results = await search('machine learning tutorials', {
category: 'tech',
status: 'published',
limit: 5
});
results.results.forEach(article => {
console.log(`${article.data.title}`);
console.log(` ${article.data.summary?.substring(0, 100)}...`);
});
Error Handling
Always handle API errors gracefully:
async function safeFetch(url) {
const response = await fetch(url);
if (!response.ok) {
const error = await response.json();
switch (error.error_code) {
case 'authentication_required':
throw new Error('Invalid or missing API credentials');
case 'access_denied':
throw new Error('Not authorized to access this resource');
case 'route_not_found':
throw new Error('Folder not found or not connected to API');
default:
throw new Error(error.message || 'Unknown error');
}
}
return response.json();
}
See Flux API Errors for all error codes.
What's Next?
You can now fetch and search your content. Two paths forward:
Secure your API — Add authentication to protect your content and control access.
Build AI applications — Connect your content to LangChain, OpenAI, or custom RAG pipelines.