Search Reference

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

Search Guide
Enterprise Reference — vectorization policies.

Search Reference

GET /api/v1/search#

POST /api/v1/search#

GET /api/v1/search/semantic#

POST /api/v1/search/semantic#

POST /api/v1/search/hybrid#

POST /api/v1/search/keyword#

POST /api/v1/search/context#

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

GET /api/v1/search/stats#

GET /api/v1/search/queue#

GET /api/v1/search/health#

Error codes#

Related#