Side Space

API reference

Search

1 endpoint · Overview

GET/v1/search

Find live files and folders across the caller's spaces by name, by what their sidecars and comments say, and by meaning
Bearer token

Every word must match the name, a non-core sidecar (tags, AI prompts, transcripts, media facts) or a live comment; any part of a word matches, case-insensitively. Name matches rank first, then closer names, then newer files. When the server has an embeddings model (SIDESPACE_EMBED_URL, ADR 0018), files close in meaning to the query follow, with matched ["meaning"] and a score, so a plain description finds files that share none of its words. Hits in a transcript or a timed comment, and pieces of a transcript close in meaning, are listed as moments. Only spaces the caller is a member of are searched.

Parameters · query

  • qstringrequired
    Words (up to 8 are matched), or a description
  • spacestring
    One space (member only); default every space
  • typestring
    videoimageaudiofolderother
  • modestring
    auto: words, then meaning when the server can; keyword: words only; meaning: meaning only (400 when the server has no model)
    autokeywordmeaning
    default "auto"
  • limitinteger
    default 50 · ≥ 1 · ≤ 200

Responses

  • 200
    Hits
    object
    › Show fields
    • itemsSearchHit[]required
      › 7 fields
      • nodeNodeInforequired
        › 11 fields
        • idstringrequired
        • space_idstringrequired
        • parent_idstring | nullrequired
          null for the space root
          required
        • namestringrequired
        • kindNodeKindrequired
          filedir
        • head_version_idstring | nullrequired
          required
        • sizeintegerrequired
        • mimestring | nullrequired
          required
        • meta_revintegerrequired
          Bumped by rename
        • deletedbooleanrequired
        • mtimeTimestamprequired
      • space_namestringrequired
      • folderstringrequired
        Path of the folder holding it, from the space root ("" at the root)
      • matchedstring[]required
        "name", the sidecar namespaces, "comments", or "meaning" for a file found by what it is about
      • snippetstring
        For a metadata or comment match, the matching value, shortened to about 120 characters
      • momentsSearchMoment[]
        Where in a video or audio file it matched, in time order
        ≤ 5 items
        › 4 fields
        • at_msinteger (int64)required
          ≥ 0
        • until_msinteger (int64)
        • textstringrequired
          The transcript line, comment or piece of transcript that matched
        • sourcestringrequired
          transcriptcommentsmeaning
      • scorenumber
        How close in meaning (cosine, 0–1), for files found by meaning
  • 4xx/5xx
    Error
    Error
Example request
curl "https://side.example.com/v1/search?q=harbor%20night" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
Example response · 200
{
  "items": [
    {
      "node": {},
      "space_name": "space_name",
      "folder": "folder",
      "matched": [],
      "snippet": "snippet",
      "moments": [],
      "score": 0.5
    }
  ]
}