Side Space

API 参考

Search

1 个接口 · 概览

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 令牌

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.

参数 · 查询

  • qstring必填
    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

响应

  • 200
    Hits
    object
    › 展开字段
    • itemsSearchHit[]必填
      › 7 个字段
      • nodeNodeInfo必填
        › 11 个字段
        • idstring必填
        • space_idstring必填
        • parent_idstring | null必填
          null for the space root
          必填
        • namestring必填
        • kindNodeKind必填
          filedir
        • head_version_idstring | null必填
          必填
        • sizeinteger必填
        • mimestring | null必填
          必填
        • meta_revinteger必填
          Bumped by rename
        • deletedboolean必填
        • mtimeTimestamp必填
      • space_namestring必填
      • folderstring必填
        Path of the folder holding it, from the space root ("" at the root)
      • matchedstring[]必填
        "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 个字段
        • at_msinteger (int64)必填
          ≥ 0
        • until_msinteger (int64)
        • textstring必填
          The transcript line, comment or piece of transcript that matched
        • sourcestring必填
          transcriptcommentsmeaning
      • scorenumber
        How close in meaning (cosine, 0–1), for files found by meaning
  • 4xx/5xx
    Error
    Error
请求示例
curl "https://side.example.com/v1/search?q=harbor%20night" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "items": [
    {
      "node": {},
      "space_name": "space_name",
      "folder": "folder",
      "matched": [],
      "snippet": "snippet",
      "moments": [],
      "score": 0.5
    }
  ]
}