# Search

Find files by name, metadata, transcripts and review comments, or by describing what's in them. Results point at the moment in a video.

```sh
curl -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  "https://side.example.com/v1/search?q=dock+at+dusk&type=video"
```

Every word has to match somewhere in the file's name or its sidecars (tags, prompts, transcripts, media facts, notes) or its review comments. Spaces the token can't reach are left out.

| Parameter | Meaning |
|---|---|
| `q` | The words, or a sentence (with `mode=meaning`) |
| `space` | Only this space |
| `type` | `video`, `image`, `audio`, `folder` or `other` |
| `mode` | `auto` (default: words first, then meaning), `keyword` or `meaning` |
| `limit` | How many hits |

## Hits and moments

```json
{
  "items": [
    {
      "node": { "id": "nod_…", "name": "A001_C003.mov", "mime": "video/quicktime", "head_version_id": "ver_…" },
      "space_name": "Film A",
      "folder": "Ep01/Shots",
      "matched": ["transcript"],
      "moments": [
        { "at_ms": 12400, "until_ms": 15100, "text": "We shot the dock right at dusk.", "source": "transcript" }
      ]
    }
  ]
}
```

When the words are in a transcript, a timed review comment or (in meaning mode) a stretch of transcript close in meaning, the hit carries **moments**: where in the media they are, with `source` `transcript`, `comments` or `meaning`. Send people straight there: the web app takes `?t=<ms>` on a file's page, and share pages take `#t=<seconds>`.

## Search by meaning

When the server has an embeddings model set up, files close in meaning follow the word matches, marked `"matched": ["meaning"]` with a `score`. So you can describe what you're after instead of guessing its file name:

```sh
sidespace search "two people arguing on a beach" --space "Film A"
#   Film A: Ep03/IMG_0042.mov  [meaning 0.62]
#         0:40.0  Look at the waves crashing on the shore.  (meaning)
```

`mode=meaning` without a model configured answers `400`. The MCP `search` tool and both SDKs take the same `mode` and return `moments` and `score` as they are.

```ts tab=TypeScript
const hits = await side.search("two people arguing on a beach", { space: "Film A", mode: "meaning" });
```

```python tab=Python
hits = side.search("two people arguing on a beach", space="Film A", mode="meaning")
```