# Search API

> POST a query to search one filesystem by filename or by meaning. Scored results, an optional subtree filter, and up to 100 matches per call.

## Search Files

```
POST /fs/:uid/search
```

Search for files within a filesystem using full-text or semantic search.

### Request Body

```json
{
  "query": "quarterly report",
  "limit": 20
}
```

### Parameters

| Field | Type | Description |
|---|---|---|
| `query` | string | Search query |
| `limit` | number | Max results (default: 20, max: 100) |
| `path` | string | Restrict search to a subtree |

### Response

```json
{
  "results": [
    {
      "uid": "node_abc123",
      "name": "Q4-Report.pdf",
      "path": "/reports/Q4-Report.pdf",
      "score": 0.95,
      "type": "file"
    }
  ]
}
```

## Search Modes

Hyperfile supports two search modes:

- **Full-text** — Matches file and folder names using fuzzy matching
- **Semantic** — Finds files related to your query by meaning

The API automatically selects the best mode based on your query. Semantic search requires that the filesystem has indexing enabled.

---

Canonical HTML version: https://hyperfile.io/docs/api/search/