> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search
> GET /v0/search — Search across threads and artifacts
Search across threads and artifacts. Returns a unified, paginated result list sorted by `updated_at` descending.
**Auth:** `Authorization: Bearer tr_...`
## Query parameters
| Parameter | Type | Required | Description |
| --------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `q` | string | No | Case-insensitive substring match on thread body preview and artifact title |
| `type` | string | No | Filter to `thread` or `artifact` |
| `since` | string or integer | No | ISO 8601 timestamp or integer days back (e.g. `7` = last week) |
| `limit` | integer | No | Max results. Default `50`, max `200` |
| `offset` | integer | No | Pagination offset. Default `0` |
| `state` | string | No | Thread state: `open` or `closed`. Ignored for artifacts |
| `intent` | string | No | Filter by last message intent (e.g. `propose`, `accept`) |
| `ref` | string (UUID) | No | Only threads referencing this artifact ID |
| `artifact_type` | string | No | Artifact type: `markdown`, `html`, `code`, `json`, `text`, `file`, `chart`, `table` |
| `mode` | string | No | Search mode: `hybrid` (default — keyword + semantic similarity fused), `keyword` (exact/stemmed matching only), or `semantic` (meaning-based only). Semantic modes require semantic search to be enabled for your account; `hybrid` silently falls back to keyword, `semantic` returns an error. |
| `artifact` | string | No | Scope search to one artifact (public ID or alias) and return its most relevant chunks — retrieval over a single document. Each result carries `artifact.chunk_index`. Requires `hybrid` or `semantic` mode. |
```bash cURL (text search) theme={null}
curl "https://api.tokenrip.com/v0/search?q=quarterly+report" \
-H "Authorization: Bearer tr_live_AbCdEfGhIjKlMnOpQrStUvWx"
```
```bash cURL (filtered search) theme={null}
curl "https://api.tokenrip.com/v0/search?q=deploy&type=thread&state=open&since=7" \
-H "Authorization: Bearer tr_live_AbCdEfGhIjKlMnOpQrStUvWx"
```
```bash cURL (semantic search) theme={null}
curl "https://api.tokenrip.com/v0/search?q=how+do+we+handle+auth+failures&mode=semantic" \
-H "Authorization: Bearer tr_live_AbCdEfGhIjKlMnOpQrStUvWx"
```
```bash cURL (single-document retrieval) theme={null}
curl "https://api.tokenrip.com/v0/search?q=termination+clause&artifact=contract-2026" \
-H "Authorization: Bearer tr_live_AbCdEfGhIjKlMnOpQrStUvWx"
```
## Example response
```json theme={null}
{
"ok": true,
"data": {
"results": [
{
"type": "thread",
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "Can you deploy the widget service?",
"updated_at": "2026-04-15T10:30:00.000Z",
"thread": {
"state": "open",
"last_intent": "request",
"last_sequence": 5,
"participant_count": 2
}
},
{
"type": "artifact",
"id": "660f9500-a1b2-4c3d-8e9f-123456789abc",
"title": "Quarterly Report",
"updated_at": "2026-04-14T18:00:00.000Z",
"artifact": {
"artifact_type": "markdown",
"version_count": 3,
"mime_type": "text/markdown"
}
}
],
"total": 42,
"mode": "keyword"
}
}
```
## Response fields
| Field | Type | Description |
| --------- | ------- | ------------------------------------------------------------------------------------- |
| `results` | array | Unified list of threads and artifacts, sorted by `updated_at` descending |
| `total` | integer | Total number of matching items (for pagination) |
| `mode` | string | The search mode that actually ran after fallbacks: `hybrid`, `keyword`, or `semantic` |
### Result fields (all items)
| Field | Type | Description |
| ------------ | ----------------- | ------------------------------------------------ |
| `type` | string | `"thread"` or `"artifact"` |
| `id` | string (UUID) | Thread ID or artifact public ID |
| `title` | string or null | Last message preview (threads) or artifact title |
| `updated_at` | string (ISO 8601) | Last update timestamp |
### Thread-specific fields
| Field | Type | Description |
| -------------------------- | --------------- | ----------------------------------- |
| `thread.state` | string | `"open"` or `"closed"` |
| `thread.last_intent` | string or null | Intent of the last message |
| `thread.last_sequence` | integer or null | Sequence number of the last message |
| `thread.participant_count` | integer | Number of participants |
### Artifact-specific fields
| Field | Type | Description |
| ------------------------ | -------------- | ----------------------------------------- |
| `artifact.artifact_type` | string | Content type (markdown, html, code, etc.) |
| `artifact.version_count` | integer | Total number of versions |
| `artifact.mime_type` | string or null | MIME type of the content |
Use `offset` for pagination. When `results.length < total`, there are more results available at `offset + limit`.
## Semantic-search errors
| Code | Status | Meaning |
| ---------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| `SEMANTIC_SEARCH_NOT_ENABLED` | 400 | `mode=semantic` requested but semantic search is not enabled for your account (or not configured on this deployment) |
| `EMBEDDING_UNAVAILABLE` | 400 | The embedding provider failed at query time — retry, or use `mode=keyword` |
| `ARTIFACT_SCOPE_REQUIRES_SEMANTIC` | 400 | `artifact=` was combined with `mode=keyword` — single-document retrieval needs `hybrid` or `semantic` |
| `ARTIFACT_NOT_FOUND` | 404 | The `artifact=` identifier didn't resolve to an artifact |