supafolio-api-docs/typesense-api-complete.md

# TypeSense API Complete Documentation

## Overview

TypeSense is an open-source, typo-tolerant search engine designed for fast, instant search experiences. Built from the ground up in C++, it offers millisecond response times with intelligent default behaviors for search-as-you-type experiences.

### Key Features
- **Open Source**: Free to use and modify (besides infrastructure costs)
- **RAM-Based Indexing**: Entire dataset should fit in RAM for optimal performance
- **Typo Tolerance**: Built-in fuzzy matching and typo correction
- **Instant Search**: Millisecond response times for typical queries
- **Privacy-Friendly**: Does not collect usage analytics or personal data
- **No Record Limits**: Only constrained by available RAM (up to 24 TB)

## Authentication

### API Key Authentication
TypeSense uses API key authentication for secure access control.

#### Method: Header-Based
```bash
curl -H "X-TYPESENSE-API-KEY: {api_key}" \
  "https://{host}/collections/{collection}/documents/search"
```

#### Configuration in Supapress Plugin
```php
function supapress_set_typesense_client() {
    $apiKey = (string)get_option('typesense_api_key');
    $host = (string)get_option('typesense_host');
    
    $client = new Client([
        'nodes' => [
            [
                'host' => $host, 
                'port' => '',
                'protocol' => 'https'  
            ]
        ],
        'api_key' => $apiKey,
        'connection_timeout_seconds' => 2
    ]);
    
    return $client;
}
```

#### Required Settings
- **`typesense_api_key`**: API authentication key
- **`typesense_host`**: TypeSense server URL (without protocol)
- **`typesense_catalog`**: Collection name for book data

#### Activation
```php
define('TYPESENSE_API', true); // Enable TypeSense in Supapress
```

## Complete API Endpoints Reference

### 1. Search Endpoint

**Endpoint**: `GET /collections/{collection}/documents/search`

**Purpose**: Primary search operation for finding documents based on text queries, filters, and faceting.

#### Complete Parameter Reference

##### Query Parameters

| Parameter | Required | Description | Default | Example |
|------------|----------|-------------|---------|---------|
| `q` | yes | The query text to search for | `"javascript programming"` |
| `query_by` | yes | Fields to search within | `"title,description"` |
| `prefix` | no | Enable prefix searching | `true` |
| `infix` | no | Enable infix search | `false` |
| `pre_segmented_query` | no | Handle query segmentation manually | `false` |
| `num_typos` | no | Max typographical errors tolerated | `2` |
| `min_len_1typo` | no | Min word length for 1 typo | `4` |
| `min_len_2typo` | no | Min word length for 2 typos | `7` |
| `drop_tokens_threshold` | no | Drop words if insufficient results | `1` |
| `typo_tokens_threshold` | no | Start typo correction after N results | `1` |
| `enable_typos_for_numerical_tokens` | no | Enable typos on numerical tokens | `true` |
| `enable_typos_for_alpha_numerical_tokens` | no | Enable typos on alphanumerical tokens | `true` |
| `synonym_num_typos` | no | Allow synonym resolution on typos | `0` |
| `split_join_tokens` | no | Treat space as typo | `fallback` |
| `drop_tokens_mode` | no | Direction of word dropping | `right_to_left` |
| `max_candidates` | no | Similar words considered for prefix/typo | `4` |
| `max_extra_prefix` | no | Max symbols before/after query | `4` |
| `max_extra_suffix` | no | Max symbols before/after query | `4` |
| `preset` | no | Preset configuration name | |
| `vector_query` | no | Vector search query | |
| `voice_query` | no | Base64 encoded speech | |
| `stopwords` | no | Comma-separated stopword sets | |
| `validate_field_names` | no | Validate field existence | `true` |

##### Filter Parameters

| Parameter | Description | Example |
|------------|-------------|---------|
| `filter_by` | Complex filtering expressions | `country: USA` |
| | | Exact match vs non-exact | `category := Shoe` (exact) vs `category: Shoe` (partial) |
| | | Multiple values | `country: [USA, UK]` |
| | | Negation | `author: != JK Rowling` |
| | | Numeric ranges | `price: [10..100]` |
| | | Multiple conditions | `price: >10 && category: Fiction` |
| | | OR conditions | `color: blue || category: shoe` |
| | | Array filtering | `genres: [Rock, Pop]` |
| | | Nested object filtering | `ingredients.{name:=cheese && concentration:<30}` |
| | | Prefix filtering | `company_name: Acm*` |
| `enable_lazy_filter` | no | Incremental filtering | `false` |
| `max_filter_by_candidates` | no | Similar words for fuzzy filter | `4` |
| `validate_field_names` | no | Validate filtered fields | `true` |

##### Ranking & Sorting Parameters

| Parameter | Description | Example |
|------------|-------------|---------|
| `sort_by` | Primary sorting control | `publicationDate:desc,title:asc` |
| | | Multiple fields with tie-breaking | `price:desc,popularity:asc,rating:desc` |
| | | Special `_text_match` field | `_text_match:desc` |
| | | Conditional sorting | `_eval(in_stock:true):desc` |
| `query_by_weights` | Field importance weighting | `title:2,description:1,author:1` |
| `text_match_type` | Text match scoring | `max_score` (default) |
| `prioritize_exact_match` | Exact match priority | `true` |
| `prioritize_token_position` | Word position priority | `false` |
| `prioritize_num_matching_fields` | Multiple field match priority | `true` |

##### Pagination Parameters

| Parameter | Description | Default |
|------------|-------------|---------|
| `page` | Page number | `1` |
| `per_page` | Results per page (max 250) | `10` |
| `offset` | Starting point | `0` |
| `limit` | Maximum hits | No limit |

##### Faceting Parameters

| Parameter | Description | Example |
|------------|-------------|---------|
| `facet_by` | Fields to facet on | `category,brand,price_range` |
| `facet_strategy` | Facet calculation method | `exhaustive` |
| `max_facet_values` | Max facet values returned | `10` |
| `facet_query` | Filter facet values | `facet_query=category:shoe` |
| `facet_query_num_typos` | Facet query fuzziness | `2` |
| `facet_return_parent` | Return parent objects | `color.name` |
| `facet_sample_percent` | Sampling percentage | `100` |
| `facet_sample_threshold` | Min hits for sampling | `0` |

##### Grouping Parameters

| Parameter | Description | Example |
|------------|-------------|---------|
| `group_by` | Field to group by | `category,company_name` |
| `group_limit` | Max hits per group | `3` |
| `group_missing_values` | Include null values in groups | `true` |

##### Results Parameters

| Parameter | Description | Example |
|------------|-------------|---------|
| `include_fields` | Fields to include | `title,author,price` |
| `exclude_fields` | Fields to exclude | `search_time_ms,out_of` |
| `highlight_fields` | Fields to highlight | `title,description` |
| `highlight_full_fields` | Full field highlighting | `title,description` |
| `highlight_affix_num_tokens` | Tokens around highlight | `4` |
| `highlight_start_tag` | Highlight start tag | `<mark>` |
| `highlight_end_tag` | Highlight end tag | `</mark>` |
| `snippet_threshold` | Full field highlight length | `30` |
| `limit_hits` | Maximum hits | `200` |
| `search_cutoff_ms` | Search timeout | No cutoff |
| `exhaustive_search` | Consider all variations | `false` |
| `use_cache` | Enable server caching | `false` |
| `cache_ttl` | Cache duration in seconds | `60` |

##### Curation Parameters

| Parameter | Description |
|------------|-------------|
| `pinned_hits` | Promote specific hits | `123:1,456:5` |
| `hidden_hits` | Hide specific hits | `123,456` |
| `enable_overrides` | Enable curation rules | `true` |
| `override_tags` | Trigger specific rules | `featured,new_release` |

#### Sample Request
```bash
curl -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books/documents/search?q=javascript&query_by=title,description&sort_by=publicationDate:desc&facet_by=category,author&per_page=20"
```

#### Sample Response
```json
{
  "hits": [
    {
      "document": {
        "id": "421",
        "title": "JavaScript: The Good Parts",
        "authors": ["Douglas Crockford"],
        "publicationDate": 1640995200,
        "categories": ["Programming", "Web Development"],
        "prices": {
          "USD": {"amount": 29.99, "discount": 5.00},
          "GBP": {"amount": 24.99, "discount": 4.00}
        },
        "image": "https://example.com/covers/js-good-parts.jpg"
      },
      "highlights": {
        "title": [
          {"value": "<mark>JavaScript</mark>", "matched_tokens": ["javascript"]}
        ]
      }
    }
  ],
  "facet_counts": [
    {
      "field_name": "categories",
      "counts": [
        {"value": "Programming", "count": 156},
        {"value": "Web Development", "count": 89},
        {"value": "Fiction", "count": 234}
      ]
    }
  ],
  "found": 1250,
  "out_of": 5000,
  "page": 1,
  "request_params": {
    "per_page": 20,
    "q": "javascript"
  },
  "search_cutoff_ms": true,
  "search_time_ms": 12
}
```

### 2. Documents Endpoint

**Endpoint**: `POST /collections/{collection}/documents`

#### Indexing Single Document
```bash
curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  -H "Content-Type: application/json" \
  -d '{"id": "123", "title": "New Book", "author": "Author Name"}' \
  "https://typesense.example.com/collections/books/documents"
```

#### Indexing Multiple Documents
```bash
curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  -H "Content-Type: application/jsonl" \
  --data-binary @books.jsonl \
  "https://typesense.example.com/collections/books/documents/import"
```

#### Retrieving Single Document
**Endpoint**: `GET /collections/{collection}/documents/{id}`

```bash
curl -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books/documents/123"
```

#### Updating Document
**Endpoint**: `PATCH /collections/{collection}/documents/{id}`

```bash
curl -X PATCH \
  -H "X-TYPESENSE-API-KEY: xyz" \
  -H "Content-Type: application/json" \
  -d '{"price": 19.99}' \
  "https://typesense.example.com/collections/books/documents/123"
```

#### Deleting Document
**Endpoint**: `DELETE /collections/{collection}/documents/{id}`

```bash
curl -X DELETE \
  -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books/documents/123"
```

### 3. Collections Endpoint

**Endpoint**: `POST /collections`

#### Create Collection
```bash
curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "books",
    "fields": [
      {"name": "title", "type": "string", "facet": true},
      {"name": "author", "type": "string", "facet": false},
      {"name": "publicationDate", "type": "int64", "facet": false},
      {"name": "price", "type": "float", "facet": true},
      {"name": "categories", "type": "string[]", "facet": true, "optional": false}
    ],
    "default_sorting_field": "publicationDate",
    "token_separators": " "
  }' \
  "https://typesense.example.com/collections"
```

#### Retrieve Collection Schema
**Endpoint**: `GET /collections/{collection}`

```bash
curl -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books"
```

#### Delete Collection
**Endpoint**: `DELETE /collections/{collection}`

```bash
curl -X DELETE \
  -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books"
```

### 4. Vector Search Endpoint

**Endpoint**: `POST /collections/{collection}/documents/search`

#### Vector Query
```bash
curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "vector_query": {
      "vector": [0.1, 0.2, 0.3, 0.4, 0.5],
      "k": 10
    },
    "query_by": "title"
  }' \
  "https://typesense.example.com/collections/books/documents/search"
```

### 5. Geo Search Endpoint

**Endpoint**: `GET /collections/{collection}/documents/search`

#### Location-based Search
```bash
curl -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books/documents/search?q=*&filter_by=location:(48.853,2.344,5.1)&sort_by=location_field_name(48.853,2.344,5.1):asc"
```

#### Geo-filtered Search
```bash
curl -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/collections/books/documents/search?q=coffee&filter_by=location:(48.853,2.344,5.1,10km)"
```

### 6. API Keys Endpoint

#### Generate Scoped Search Key
**Endpoint**: `POST /keys`

```bash
curl -X POST \
  -H "X-TYPESENSE-API-KEY: master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Public search key for website",
    "actions": ["documents:search"],
    "collections": ["books"],
    "expires_at": 1735689599
  }' \
  "https://typesense.example.com/keys"
```

#### List API Keys
**Endpoint**: `GET /keys`

```bash
curl -H "X-TYPESENSE-API-KEY: master_key" \
  "https://typesense.example.com/keys"
```

#### Delete API Key
**Endpoint**: `DELETE /keys/{id}`

```bash
curl -X DELETE \
  -H "X-TYPESENSE-API-KEY: master_key" \
  "https://typesense.example.com/keys/123"
```

### 7. Cluster Operations

#### Create Snapshot
**Endpoint**: `POST /operations/snapshot`

```bash
curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/operations/snapshot"
```

#### Compact Database
**Endpoint**: `POST /operations/db/compact`

```bash
curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/operations/db/compact"
```

#### Clear Cache
**Endpoint**: `POST /operations/cache/clear`

```bash
curl -X POST \
  -H "X-TYPESENSE-API-KEY: xyz" \
  "https://typesense.example.com/operations/cache/clear"
```

## Data Schema for Book Collections

### Core Fields

```json
{
  "id": "string (unique identifier)",
  "title": "string (full title)",
  "subtitle": "string (subtitle/edition)",
  "description": "string (full description)",
  "summary": "string (brief summary)",
  "authors": ["string array (author names)"],
  "publicationDate": "timestamp (Unix epoch)",
  "saleDate": "timestamp (Unix epoch)",
  "publisher": "string (publisher name)",
  "imprint": "string (imprint name)",
  "isbn13": "string (ISBN-13)",
  "isbn10": "string (ISBN-10)",
  "pages": "integer (page count)",
  "language": "string (language code)",
  "categories": ["string array (subject categories)"],
  "collections": ["string array (series collections)"],
  "formats": [
    {
      "format": {"name": "string", "format_id": "number"},
      "isbn": "string"
    }
  ],
  "prices": {
    "USD": {"amount": "number", "discount": "number"},
    "GBP": {"amount": "number", "discount": "number"},
    "CAD": {"amount": "number", "discount": "number"},
    "EUR": {"amount": "number", "discount": "number"}
  },
  "image": "url (cover image URL)",
  "assets": [
    {
      "asset": {
        "type": "string",
        "sub_type": "string",
        "path": "url",
        "width": "number",
        "height": "number"
      }
    }
  ],
  "trim": {
    "width": "number",
    "height": "number", 
    "depth": "number",
    "unit": "string"
  },
  "weight": {
    "weight": "number",
    "weight_unit": "string"
  },
  "edition": "string",
  "awards": [
    {
      "award": {"name": "string", "id": "number"}
    }
  ],
  "reviews": [
    {
      "review": {"description": "string"}
    }
  ],
  "retailers": [
    {
      "label": "string",
      "path": "string", 
      "seo": "string"
    }
  ]
}
```

### Faceted Fields Configuration

```json
{
  "fields": [
    {
      "name": "categories",
      "type": "string[]",
      "facet": true,
      "optional": false
    },
    {
      "name": "author",
      "type": "string",
      "facet": true
    },
    {
      "name": "publicationDate",
      "type": "int64",
      "facet": false
    },
    {
      "name": "price",
      "type": "float",
      "facet": true,
      "optional": false
    }
  ]
}
```

## Advanced Features

### Typo Tolerance
- **Damerau-Levenshtein distance** for calculating edit distance
- **Configurable tolerance levels** (0, 1, 2 typos)
- **Prefix/Infix search** for autocomplete scenarios
- **Split join tokens** for space-as-typo handling

### Faceting Capabilities
- **Exhaustive vs Top Values** strategies for performance
- **Numerical range faceting** with custom labels
- **Nested object faceting** for complex data structures
- **Facet query filtering** for drill-down scenarios

### Sorting Options
- **Multi-field sorting** with tie-breaking
- **Text match score** sorting by relevance
- **Conditional expressions** for dynamic sorting
- **Decay functions** for time-based relevance
- **Random sorting** with seed control

### Caching & Performance
- **Query result caching** with TTL control
- **RAM-based indexing** for instant search
- **Connection pooling** for high throughput
- **Lazy filtering** for large datasets

## Error Handling

### Common Error Responses

```json
{
  "message": "No such collection found.",
  "code": 404
}
```

```json
{
  "message": "Bad request.", 
  "code": 400
}
```

### Error Codes Reference

| Code | Description | Solution |
|-------|-------------|----------|
| 400 | Bad Request | Check JSON syntax, required parameters |
| 401 | Unauthorized | Verify API key in headers |
| 404 | Not Found | Check collection/document existence |
| 409 | Conflict | Document ID already exists |
| 422 | Unprocessable | Validate field types/values |
| 429 | Too Many Requests | Implement rate limiting |
| 500 | Internal Error | Contact TypeSense support |

## Performance Optimization

### Indexing Strategy
- **RAM allocation**: Plan for 2x dataset size
- **Field selection**: Search only relevant fields
- **Schema optimization**: Enable sorting on frequently filtered fields
- **Tokenizer configuration**: Custom separators for content

### Query Optimization
- **Prefix queries**: Use `prefix=true` for autocomplete
- **Field weighting**: Prioritize important fields
- **Filter early**: Apply `filter_by` before full text search
- **Limit results**: Use `per_page` appropriately

### Caching Strategy
- **Server-side**: Enable `use_cache=true` for repeated queries
- **Client-side**: Implement application-level caching
- **TTL management**: Set appropriate `cache_ttl` values

## Integration Examples

### Basic Search Implementation
```javascript
const client = new TypesenseClient({
  nodes: [{
    host: 'typesense.example.com',
    port: '443',
    protocol: 'https'
  }],
  apiKey: 'xyz',
  connectionTimeoutSeconds: 2
});

const searchResults = await client.collections('books')
  .documents()
  .search({
    q: 'javascript programming',
    query_by: 'title,description',
    facet_by: 'categories,author',
    sort_by: 'publicationDate:desc',
    per_page: 20
  });
```

### Faceted Search with Filters
```javascript
const results = await client.collections('books')
  .documents()
  .search({
    q: '*',
    filter_by: 'categories:[Programming,Web Development] && price:[20..50]',
    facet_by: 'categories,author,publicationYear',
    max_facet_values: 15,
    sort_by: 'price:asc,title:asc'
  });
```

### Auto-complete Implementation
```javascript
const suggestions = await client.collections('books')
  .documents()
  .search({
    q: userQuery,
    query_by: 'title,author',
    prefix: true,
    per_page: 8,
    highlight_fields: 'title',
    highlight_affix_num_tokens: 2
  });
```

---

**Generated**: 2026-01-24  
**TypeSense Version**: v29.0  
**Supapress Plugin**: v2.26.2