---
title: Search Reference
path: reference/search
status: published
---

Keyword, semantic, hybrid search, and RAG context endpoints.

**Base path:** `/api/v1/search/`

All results respect caller permissions.

## GET /api/v1/search

Keyword search.

**Query:**

| Param | Notes |
|-------|-------|
| `q` | Query string |
| `share_id` | Scope to one share |
| `file_type` | MIME pattern |
| `recursive` | Default true |
| `limit` | 1–100, default 50 |
| `offset` | |

**Response:** `{query, results: [...], total, has_more}`. Each result:

```json
{
  "id": "fil_01J3K",
  "name": "annual-report-2025.pdf",
  "type": "file",
  "share_id": "shr_01J3H",
  "folder_id": "fld_01J3I",
  "path": "/Finance/annual-report-2025.pdf",
  "mime_type": "application/pdf",
  "size": 5820193,
  "modified_at": "2026-04-20T10:00:00Z",
  "score": 8.42
}
```

## POST /api/v1/search

Same as GET with a JSON body.

**Body:** `query`, `share_id`, `mime_type`, `limit`, `offset`.

## GET /api/v1/search/semantic

Vector search. Requires tenant vectorization to be configured.

**Query:**

| Param | Notes |
|-------|-------|
| `q` | Natural-language query |
| `share_id` | Scope to one share |
| `limit` | 1–50, default 20 |

**Response:** `{semantic_results: [...]}`. Each result:

```json
{
  "file_id": "fil_01J3K",
  "file_name": "annual-report-2025.pdf",
  "share_id": "shr_01J3H",
  "path": "/Finance/annual-report-2025.pdf",
  "chunk_content": "Q4 2024 bookings totaled $42.3M...",
  "chunk_index": 17,
  "page": 12,
  "section": "Financial Highlights",
  "score": 0.89,
  "distance": 0.11
}
```

## POST /api/v1/search/semantic

Same as GET with richer filters.

**Body:**

| Field | Notes |
|-------|-------|
| `query` | Required |
| `share_id` | |
| `file_types` | Array of MIME strings |
| `path_prefix` | Match path prefix |
| `limit` | |

## POST /api/v1/search/hybrid

Blend BM25 and vector scores.

**Body:**

| Field | Notes |
|-------|-------|
| `query` | Required |
| `share_id` | |
| `file_types` | Array of MIMEs |
| `limit` | |
| `alpha` | 0.0–1.0, blend factor (0 = BM25 only, 1 = vector only), default 0.7 |

**Response:** `{hybrid_results: [...]}`. Shape like semantic.

## POST /api/v1/search/keyword

BM25 keyword search POST variant.

**Body:** `query`, `share_id`, `file_types`, `limit`.

## POST /api/v1/search/context

RAG context — returns search results pre-formatted as an LLM context string.

**Body:**

| Field | Notes |
|-------|-------|
| `query` | Required |
| `share_id` | |
| `file_types` | |
| `max_tokens` | Token cap for the context string |
| `max_chunks` | Max chunks included |

**Response:**

```json
{
  "context": "[1] From annual-report-2025.pdf, page 12: Q4 2024 bookings totaled...",
  "chunks": [
    {
      "content": "Q4 2024 bookings...",
      "file_id": "fil_01J3K",
      "file_name": "annual-report-2025.pdf",
      "path": "/Finance/annual-report-2025.pdf",
      "page": 12,
      "section": "Financial Highlights",
      "score": 0.89
    }
  ],
  "estimated_tokens": 1234
}
```

## GET /api/v1/search/index-status/{file_id}

Check indexing status for one file.

**Required permission:** `READ`.

**Response:**

```json
{
  "is_indexed": true,
  "chunk_count": 42,
  "last_indexed": "2026-04-20T10:30:00Z",
  "error": null
}
```

## GET /api/v1/search/stats

Tenant-wide index statistics.

**Response:**

```json
{
  "total_chunks": 1842391,
  "total_files_indexed": 8423
}
```

## GET /api/v1/search/queue

Vectorization queue status.

**Query:** `limit` (1–100, default 20).

**Response:**

```json
{
  "pending_count": 42,
  "indexed_count": 8423,
  "pending_files": [{"file_id": "fil_...", "queued_at": "..."}],
  "recently_indexed": [{"file_id": "fil_...", "indexed_at": "...", "chunk_count": 42}],
  "errors_last_hour": 0
}
```

## GET /api/v1/search/health

Check vectorization subsystem health. No authentication.

**Response:**

```json
{
  "weaviate_connected": true,
  "embedding_service_available": true,
  "status": "healthy",
  "provider_name": "openai"
}
```

## Error codes

| Code | HTTP | When |
|------|------|------|
| `VALIDATION_ERROR` | 422 | Missing/invalid parameters |
| `SERVICE_UNAVAILABLE` | 503 | Weaviate or embedding provider down |
| `AUTHZ_PERMISSION_DENIED` | 403 | No access to requested share |

## Related

- [Search Guide](/docs/scaidrive/api-guides/search)
- [Enterprise Reference](/docs/scaidrive/reference/enterprise) — vectorization policies.