Search

OxiCloud provides authenticated file and folder search with a cursor-paginated response, filter/sort query parameters, recursive traversal, and in-memory result caching.

Endpoints

Method	Endpoint	Description
GET	/api/search	Cursor-paginated search
GET	/api/search/suggest	Lightweight autocomplete suggestions
DELETE	/api/admin/search/cache	Flush the shared search results cache (admin only)

All search endpoints require authentication. The cache flush is additionally restricted to administrators — see Result Caching.

Query Parameters

Parameter	Description
query	Text to search in file/folder names (and file content when the Tantivy index is enabled)
type	Comma-separated file extensions (files only)
folder_id	Restrict search scope to one folder
recursive	Search subfolders, defaults to true
created_after / created_before	Filter by creation time (unix seconds)
modified_after / modified_before	Filter by modification time
min_size / max_size	Filter by file size in bytes
resource_types	Comma-separated: file, folder (both by default)
order_by	Sort dimension: relevance (default), name, size, updated_at, created_at
reverse	Reverse sort direction (no-op for relevance)
limit	Page size (1–200, default 50)
cursor	Opaque cursor returned by the previous page

Response Shape

/api/search returns the same envelope as every other /*/resources listing (folders, favorites, recent, trash, shared) so a single client component can render all of them:

{
  "items": [
    {
      "resource_type": "file",
      "resource": { "id": "…", "name": "report.pdf", "size": 12345, "…": "…" },
      "meta": {
        "score": 0.82,
        "snippet": "…quarterly <mark>report</mark>…",
        "via": "content"
      }
    },
    {
      "resource_type": "folder",
      "resource": { "id": "…", "name": "Reports", "…": "…" },
      "meta": { "score": 0.31, "via": "name" }
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjUwLCJvcmRlcl9ieSI6InJlbGV2YW5jZSJ9",
  "query_time_ms": 12,
  "total": 137
}

• resource_type: "file" or "folder" — tells the client which variant of resource to render.
• resource: the same FileDto / FolderDto shape any other endpoint would emit.
• meta.score: relevance in [0, 1].
• meta.snippet: optional HTML-safe excerpt from the content index (present only when the match came from file content).
• meta.via: "name", "content", or "path" — where the match fired.
• next_cursor: opaque; present iff another page exists. Pass it verbatim as ?cursor=… for the next call.
• total: integer, approximate — reflects the caller-visible match count (permission-filtered). Omitted when unknown; never leaks a count for rows the caller cannot see.

Example

curl -H "Authorization: Bearer $TOKEN" \
  "https://oxicloud.example.com/api/search?query=report&type=pdf,docx&limit=20"

Suggestions

Use /api/search/suggest?query=rep&limit=10 for quick autocomplete-style results. Suggestions can also be scoped to a folder with folder_id.

Result Caching

Search results are cached in memory using the search criteria and user ID as the cache key.

• Cache TTL: 5 minutes
• Max entries: 1000
• Manual invalidation: DELETE /api/admin/search/cache — admin-only. The endpoint calls invalidate_all() on the shared moka cache, so one call cold-starts every subsequent search for every tenant; it's an operator debug lever, not a per-user affordance.

Feature Flag

Search can be disabled with OXICLOUD_ENABLE_SEARCH=false.