Search API
## Overview
The SearchJet Search API provides powerful full-text search capabilities with built-in typo tolerance, relevance ranking, filtering, sorting, and faceted results. All search requests are made via `GET` to the search endpoint.
**Base URL:**
```
https://app.searchjetengine.com/api/v1/search
```
All requests must include your API key for authentication.
---
## Authentication
Every search request requires a Bearer token in the `Authorization` header. Generate an API key from your SearchJet dashboard under **Settings > API Keys**.
```
Authorization: Bearer YOUR_API_KEY
```
Never expose your API key in client-side code. Always route search requests through your backend server.
---
## Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `q` | string | Yes | — | The search query string |
| `limit` | integer | No | 20 | Number of results per page (max 100) |
| `offset` | integer | No | 0 | Number of results to skip |
| `page` | integer | No | 1 | Page number (alternative to offset) |
| `filters` | string | No | — | Filter expression string |
| `sort` | string | No | — | Sort expression string |
| `facets` | string | No | — | Comma-separated facet field names |
| `attributesToRetrieve` | string | No | * | Comma-separated fields to return |
| `attributesToHighlight` | string | No | — | Fields to highlight matches in |
---
## Filter Syntax
Filters use a SQL-like expression syntax parsed by the SearchJet engine.
### Equality
```
status = "published"
category = "technology"
```
### Comparison Operators
```
price > 50
price >= 100
rating < 4.5
created_at <= "2025-01-01"
```
### Arrays (IN / NOT IN)
```
status IN ["published", "draft"]
category NOT ["archived", "deleted"]
```
### Logical Operators (AND / OR)
```
status = "published" AND category = "technology"
status = "published" OR status = "draft"
price > 50 AND (category = "electronics" OR category = "gadgets")
```
### Existence Checks
```
author EXISTS
deleted_at NOT EXISTS
```
### Combining Filters
```
status = "published" AND (category = "tech" OR category = "science") AND price > 20
```
---
## Sort Syntax
Sort by one or more fields in ascending (`asc`) or descending (`desc`) order.
```
sort=published_at:desc
sort=rating:desc,published_at:asc
sort=relevance:desc
```
Use `relevance:desc` to sort by search relevance score (default when no sort is specified).
---
## Response Format
```json
{
"query": "wireless headphones",
"hits": [
{
"id": "doc_abc123",
"title": "Premium Wireless Headphones",
"slug": "premium-wireless-headphones",
"content": "Experience crystal-clear audio...",
"price": 149.99,
"category": "electronics",
"rating": 4.7,
"published_at": "2025-06-15T10:00:00Z",
"_formatted": {
"title": "Premium Wireless Headphones",
"content": "Experience crystal-clear audio..."
}
}
],
"nbHits": 342,
"page": 1,
"hitsPerPage": 20,
"nbPages": 18,
"processingTimeMs": 12,
"facets": {
"category": {
"electronics": 156,
"accessories": 89,
"audio": 97
}
},
"params": "q=wireless+headphones&limit=20"
}
```
### Response Fields
| Field | Type | Description |
|---|---|---|
| `query` | string | The original search query |
| `hits` | array | Array of matching documents |
| `nbHits` | integer | Total number of matching results |
| `page` | integer | Current page number |
| `hitsPerPage` | integer | Number of results per page |
| `nbPages` | integer | Total number of pages |
| `processingTimeMs` | integer | Server processing time in milliseconds |
| `facets` | object | Facet counts (if requested) |
| `hits._formatted` | object | Highlighted versions of requested fields |
---
## Code Examples
### cURL
```bash
curl -X GET "https://app.searchjetengine.com/api/v1/search?q=wireless+headphones&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
```
### JavaScript (Fetch)
```javascript
const searchJet = async (query) => {
const params = new URLSearchParams({
q: query,
limit: 10,
facets: "category,brand",
attributesToHighlight: "title,content"
});
const response = await fetch(
`https://app.searchjetengine.com/api/v1/search?${params}`,
{
headers: {
Authorization: `Bearer ${process.env.SEARCHJET_API_KEY}`
}
}
);
return response.json();
};
const results = await searchJet("wireless headphones");
console.log(`Found ${results.nbHits} results in ${results.processingTimeMs}ms`);
```
### Python (requests)
```python
import requests
def search(query, limit=10):
response = requests.get(
"https://app.searchjetengine.com/api/v1/search",
headers={"Authorization": "Bearer YOUR_API_KEY"},
params={
"q": query,
"limit": limit,
"facets": "category,brand"
}
)
return response.json()
results = search("wireless headphones")
print(f"Found {results['nbHits']} results")
for hit in results["hits"]:
print(f" - {hit['title']}")
```
### PHP (Guzzle)
```php
use GuzzleHttp\Client;
$client = new Client([
'base_uri' => 'https://app.searchjetengine.com',
'headers' => [
'Authorization' => 'Bearer YOUR_API_KEY'
]
]);
$response = $client->get('/api/v1/search', [
'query' => [
'q' => 'wireless headphones',
'limit' => 10,
'facets' => 'category,brand'
]
]);
$data = json_decode($response->getBody(), true);
echo "Found {$data['nbHits']} results\n";
```
---
## Pagination
### Offset-Based Pagination
Use `offset` and `limit` for traditional pagination. Set `offset` to `limit * (page - 1)`.
```
?page=1 — offset=0, limit=20
?page=2 — offset=20, limit=20
?page=3 — offset=40, limit=20
```
### Page-Based Pagination
Use the `page` parameter directly. SearchJet handles offset calculation internally.
```
?page=1&limit=20
?page=2&limit=20
```
Page-based is simpler for UI implementations. Offset-based offers more control for infinite scroll patterns.
---
## Performance Tips
- **Narrow `attributesToRetrieve`** to only the fields your application needs. This reduces payload size and improves response times.
- **Use `limit` wisely.** Requesting 100 results when you display 10 wastes bandwidth. Paginate instead.
- **Cache popular queries** on your server with a short TTL (60-300 seconds) to reduce API calls.
- **Prefer server-side search** over client-side to protect your API key and enable caching.
- **Use facets strategically.** Faceting on high-cardinality fields increases processing time. Facet only on fields with a reasonable number of unique values.
---
## Related Pages
- [Error Handling](/docs/error-handling) — Understand error codes and recovery strategies
- [Rate Limits](/docs/rate-limits) — Plan details and quotas
- [API Key Setup](/docs/api-key-setup) — Generate and manage your keys