# Torque - Full LLM Reference

> Torque is Truespar's in-memory search engine with full disk persistence. It implements the Typesense v30.1 REST API and adds a high-throughput binary TCP ingest protocol, TQBF binary file uploads, and an MCP server for AI assistants.

## Overview

- **Version:** 0.6.1
- **HTTP API + Studio:** port 8108 (configurable via `--api-addr`)
- **TCP binary ingest:** port 8109 (configurable via `--ingest-addr`)
- **Auth header:** `X-TYPESENSE-API-KEY`
- **MCP endpoint:** `POST /api/mcp` (JSON-RPC 2.0, protocol version 2025-11-25)
- **Typesense v30.1 compatible:** existing Typesense client libraries work without code changes
- **Persistence:** automatic to `--data-dir`; all data restored on restart
- **Languages:** English, Swedish, Norwegian, Danish, Finnish, German, French, Spanish, Portuguese, Italian, Dutch, Russian, Arabic, Greek, Hungarian, Romanian, Turkish

## Installation

The download endpoints below are **version-agnostic** - they always resolve to
the current release, so no version needs to be pinned. Valid `platform` values
are `linux-x64` and `windows-x64` (there is no macOS build).

**Linux (x86-64):**

```
curl -L "https://truespar.com/api/versions/torque/latest/download?platform=linux-x64" -o torque.tar.gz
tar xzf torque.tar.gz
./torque-server --api-key YOUR_KEY --license-key YOUR_LICENSE
```

**Windows (x86-64):** download
`https://truespar.com/api/versions/torque/latest/download?platform=windows-x64`
(a `.zip` containing `torque-server.exe` and `torque-admin.exe`), extract, then
run `torque-server.exe --api-key YOUR_KEY --license-key YOUR_LICENSE`.

**Docker:** `docker pull truespar/torque` - expose port 8108, mount a `/data` volume.

The Linux tarball ships a detached GPG signature (`.asc`) and a SHA-256 checksum;
Windows binaries are Authenticode-signed.

### Version discovery (for automation)

`GET https://truespar.com/api/versions/torque/latest?platform=linux-x64` returns
JSON: `{"version": "0.6.1", "releaseNotes": "...", "publishedAt": "...", "downloadAvailable": true}`.
Use `platform=windows-x64` for the Windows build. Human-readable install guide:
https://truespar.com/torque/docs/v1/getting-started

## HTTP API Endpoints

### Health & Status (no auth required)

- `GET /health` - server status, version, license info
- `GET /health/ready` - readiness probe (200 when collections loaded)
- `GET /metrics` - Prometheus-format metrics
- `GET /admin/stats` - memory breakdown per collection
- `GET /debug` - version, build info

### Collections

- `POST /collections` - create collection (JSON body with name, fields array)
- `GET /collections` - list all collections
- `GET /collections/{name}` - get collection schema and doc count
- `PATCH /collections/{name}` - update schema (add or drop fields)
- `DELETE /collections/{name}` - delete collection (requires `--allow-drop-collection`)

### Documents

- `GET /collections/{name}/documents/search` - search documents
- `POST /collections/{name}/documents/import` - JSONL import (`?action=create|upsert|update`)
- `POST /collections/{name}/documents/import-binary` - TQBF binary file upload
- `GET /collections/{name}/documents/export` - export as JSONL stream
- `POST /collections/{name}/documents` - create single document
- `GET /collections/{name}/documents/{id}` - get document by ID
- `PATCH /collections/{name}/documents/{id}` - partial update (merge fields)
- `DELETE /collections/{name}/documents/{id}` - delete document
- `DELETE /collections/{name}/documents?filter_by=...` - bulk delete by filter
- `POST /collections/{name}/documents/compact` - trigger compaction (realtime mode)

### Multi-Search

- `POST /multi_search` - body: `{"searches": [{"collection": "...", "q": "...", "query_by": "..."}]}`

### Aliases

- `GET /aliases` - list aliases
- `PUT /aliases/{name}` - create/update alias: `{"collection_name": "target"}`
- `GET /aliases/{name}` - get alias
- `DELETE /aliases/{name}` - delete alias

### Synonyms

- `GET /synonym_sets` - list synonym sets
- `PUT /synonym_sets/{name}` - create/update set
- `GET/DELETE /synonym_sets/{name}` - get or delete set
- `PUT /synonym_sets/{name}/items/{id}` - create/update synonym item
- `GET/DELETE /synonym_sets/{name}/items/{id}` - get or delete item

### Presets

- `GET /presets` - list presets
- `PUT /presets/{id}` - create/update preset
- `GET/DELETE /presets/{id}` - get or delete preset

### Stopwords

- `GET /stopwords` - list stopword sets
- `PUT /stopwords/{id}` - create/update stopword set
- `GET/DELETE /stopwords/{id}` - get or delete set

### API Keys

- `POST /keys` - create key (body: description, actions, collections, optional expires_at)
- `GET /keys` - list keys (metadata only, key values not shown)
- `GET /keys/{id}` - get key metadata
- `DELETE /keys/{id}` - delete key

### MCP Server

- `POST /api/mcp` - JSON-RPC 2.0 (Streamable HTTP transport)

## Collection Schema

```json
{
  "name": "products",
  "fields": [
    {"name": "title", "type": "string"},
    {"name": "price", "type": "float", "sort": true},
    {"name": "brand", "type": "string", "facet": true},
    {"name": "tags", "type": "string[]", "optional": true}
  ],
  "default_sorting_field": "price",
  "enable_nested_fields": false
}
```

### Field Types

| Type | Description |
|------|-------------|
| `string` | Full-text searchable text |
| `string[]` | Array of strings |
| `int32` | 32-bit integer |
| `int64` | 64-bit integer |
| `float` | 64-bit float |
| `bool` | Boolean |
| `int32[]`, `int64[]` | Integer arrays |
| `geopoint` | Latitude/longitude pair `[lat, lng]` |
| `float[]` | Vector embedding (requires `num_dim`) |

### Field Options

| Option | Default | Description |
|--------|---------|-------------|
| `facet` | false | Enable facet counting |
| `sort` | false | Enable sort_by on this field |
| `index` | true | Index for search/filtering |
| `optional` | false | Allow documents without this field |
| `stem` | true | Apply language stemming |
| `locale` | - | Language override (e.g., `sv`, `de`) |
| `num_dim` | - | Vector dimensions (required for `float[]`) |

### Index Modes

- **Batch** (default): full index rebuild on commit. Best for bulk loads.
- **Realtime**: instant upsert/delete via overlay. Set `"index_mode": "realtime"` on creation.

## Search Parameters

`GET /collections/{name}/documents/search`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `q` | string | required | Search query. Use `*` for match-all. |
| `query_by` | string | required | Comma-separated searchable fields |
| `filter_by` | string | - | Filter expression |
| `sort_by` | string | - | Sort expression |
| `facet_by` | string | - | Comma-separated fields to facet |
| `group_by` | string | - | Group results by field |
| `group_limit` | int | 3 | Max results per group |
| `per_page` | int | 10 | Results per page (max 250) |
| `page` | int | 1 | Page number |
| `num_typos` | int | 2 | Typo tolerance (0-2) |
| `prefix` | bool | true | Prefix matching on last token |
| `query_by_weights` | string | - | Weights per query_by field |
| `highlight_fields` | string | - | Fields to highlight |
| `highlight_start_tag` | string | `<mark>` | Highlight open tag |
| `highlight_end_tag` | string | `</mark>` | Highlight close tag |
| `vector_query` | string | - | Vector search expression |
| `pinned_hits` | string | - | Pin documents: `id1:1,id2:2` |
| `hidden_hits` | string | - | Exclude documents: `id1,id2` |
| `preset` | string | - | Apply saved preset |
| `synonym_sets` | string | - | Comma-separated synonym set names |
| `stopwords` | string | - | Stopword set name |
| `max_facet_values` | int | 10 | Max facet values per field |
| `facet_query` | string | - | Filter facet values by prefix |
| `text_match_type` | string | - | `all` or `any` token matching |

## Filter Syntax

```
filter_by=price:>100 && brand:=Acme
filter_by=category:=[Shoes, Boots] && in_stock:true
filter_by=price:10..500
filter_by=location:(40.7128, -74.0060, 50 km)
filter_by=variants:(color:=Black && size:=M)
```

| Operator | Example |
|----------|---------|
| `:=` | Exact match: `brand:=Acme` |
| `:!=` | Not equal: `brand:!=Acme` |
| `:>`, `:>=`, `:<`, `:<=` | Numeric comparison: `price:>100` |
| `:..` | Range (inclusive): `price:10..500` |
| `:[val1, val2]` | Multi-value OR: `tags:=[red, blue]` |
| `:=ALL[val1, val2]` | Multi-value AND: `tags:=ALL[red, blue]` |
| `&&` | AND |
| `\|\|` | OR |
| `(lat, lng, dist unit)` | Geo radius: `location:(40.71, -74.00, 50 km)` |

Nested element-level AND (requires `enable_nested_fields: true`):
`variants:(color:=Black && size:=M)` - matches array elements where BOTH conditions hold.

## Sort Syntax

```
sort_by=price:desc
sort_by=_text_match:desc,price:asc
sort_by=location(40.7128, -74.0060):asc
sort_by=_vector_distance:asc
sort_by=created_at(origin:NOW,func:gauss,scale:7d):desc
```

Decay functions: `gauss`, `linear`, `exp`, `diff` with parameters `origin`, `func`, `scale`, optional `decay`, `offset`.

## Vector Search

Schema: `{"name": "embedding", "type": "float[]", "num_dim": 768}`

Query: `vector_query=embedding:([0.12, -0.34, ...], k:10)`

Find similar: `vector_query=embedding:(id:doc_123, k:10)`

Parameters inside parentheses: `k` (neighbors), `distance_threshold`, `ef` (beam width), `flat_search_cutoff`, `alpha` (hybrid weight: 0.0=text, 1.0=vector).

Distance metrics (set on field): `cosine` (default), `ip`, `l2`.

Hybrid search combines BM25F text + vector via Reciprocal Rank Fusion (default) or alpha-weighted score interpolation.

## MCP Server

Endpoint: `POST /api/mcp` - JSON-RPC 2.0, Streamable HTTP transport, protocol version 2025-11-25.

Auth: same `X-TYPESENSE-API-KEY` header as HTTP API.

### Available Tools

| Tool | Type | Required Args | Description |
|------|------|---------------|-------------|
| `search` | Read | `collection`, `q`, `query_by` | Full-text search with filters, facets, sorting |
| `multi_search` | Read | `searches` (array) | Multiple searches in parallel |
| `collections` | Read | - | List collections with doc counts |
| `schema` | Read | `collection` | Get field schema for a collection |
| `get_document` | Read | `collection`, `id` | Retrieve document by ID |
| `create_collection` | Write | `name`, `fields` | Create collection with typed fields |
| `upsert_document` | Write | `collection`, `document` | Insert or replace document |
| `delete_document` | Write | `collection`, `id` | Delete document by ID |
| `delete_collection` | Write | `collection` | Delete collection (requires `--allow-drop-collection`) |

### Claude Desktop Configuration

```json
{
  "mcpServers": {
    "torque": {
      "url": "http://localhost:8108/api/mcp",
      "headers": {
        "X-TYPESENSE-API-KEY": "your-api-key"
      }
    }
  }
}
```

### Protocol Flow

1. `initialize` - handshake with protocol version and capabilities
2. `tools/list` - discover available tools
3. `tools/call` - execute a tool with arguments
4. `ping` - health check

## Ingestion Methods

| Method | Endpoint/Port | Best For |
|--------|---------------|----------|
| HTTP JSONL | `POST /collections/{name}/documents/import` | Small updates, Typesense compatibility |
| TCP Binary | port 8109 | Live streaming from databases (70K docs/s) |
| TQBF File | `POST /collections/{name}/documents/import-binary` | Bulk import, ETL pipelines |

## Client SDKs

| Language | Package | Install |
|----------|---------|---------|
| .NET 10+ | `Torque.Http` | `dotnet add package Torque.Http` |
| Python 3.10+ | `torque-http` | `pip install torque-http` |
| Node.js 20+ | `@truespar/torque-http` | `npm install @truespar/torque-http` |
| Java 21+ | `com.truespar:torque-http` | Maven Central dependency |
| Go 1.23+ | `torque-sdk-go` | Download from truespar.com, use `go.mod replace` |

All SDKs include: HTTP search API, TCP binary ingest client, TQBF binary file writer. Zero external runtime dependencies.

## API Keys

| Action | Description |
|--------|-------------|
| `documents:search` | Search across allowed collections |
| `documents:*` | All document operations |
| `collections:*` | All collection operations |
| `keys:*` | Manage API keys |
| `synonyms:*` | Manage synonym sets |
| `presets:*` | Manage presets |
| `stopwords:*` | Manage stopword sets |
| `*` | Full access |

Scoped search keys (HMAC-signed) can be generated client-side to embed per-user restrictions.

## Server Configuration

| Flag | Default | Description |
|------|---------|-------------|
| `--api-key` | auto-generated | Bootstrap API key |
| `--api-addr` | `0.0.0.0:8108` | HTTP listen address |
| `--ingest-addr` | `0.0.0.0:8109` | TCP ingest address |
| `--data-dir` | `./data` | Persistence directory |
| `--log-level` | `info` | trace, debug, info, warn, error |
| `--cors-origins` | `*` | CORS allowed origins |
| `--tls-cert` | - | TLS certificate (PEM) |
| `--tls-key` | - | TLS private key (PEM) |
| `--slow-query-ms` | `0` | Slow query threshold (0=disabled) |
| `--query-timeout-ms` | `10000` | Query timeout |
| `--license-key` | - | Truespar license key |
| `--allow-drop-collection` | false | Enable collection deletion |
| `--no-studio` | false | Disable Studio web UI |
| `--max-memory-percent` | `90` | Max memory as % of system RAM |
| `--max-http-body-bytes` | 128 MB | Max HTTP body size |

Environment variables use `TORQUE_` prefix (e.g., `TORQUE_API_KEY`). TOML config file: `torque.toml` in working directory or `--config path`.

Priority: CLI flags > environment variables > TOML config > defaults.

## Error Response Format

```json
{"message": "error description"}
```

Status codes: 200 (success), 201 (created), 400 (invalid input), 401 (missing/invalid key), 403 (forbidden), 404 (not found), 409 (conflict), 500 (server error).