Side Space

API 参考

Files and folders

9 个接口 · 概览

GET/v1/spaces/{sid}/paths/{path}

The live file or folder at a path, or with as_of what was there then
Bearer 令牌

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • pathstring必填
    e.g. Ep01/Shots/a.mov (slashes kept); empty = the root

参数 · 查询

  • as_ofstring
    Read the space as it was: an RFC 3339 time, a duration ago ("-2h", "-90m"), or a journal seq. The answer's Sidespace-As-Of-Seq header names the last change included. Versions are kept until a file is deleted for good, so a past head_version_id can be downloaded as usual.

响应

请求示例
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/paths/Ep01/Shots/A001_C003.mov" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "parent_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "name": "A001_C003.mov",
  "kind": "file",
  "head_version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
  "size": 734003200,
  "mime": "video/quicktime",
  "meta_rev": 1,
  "deleted": false,
  "mtime": "2026-11-14T09:30:00Z"
}

POST/v1/spaces/{sid}/nodes

Create a folder or an empty file (editor). A clashing name gets a " (2)" suffix; the response has the final name.
Bearer 令牌

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$

参数 · 请求头

  • If-None-Matchstring
    "*": write only if nothing is there yet (no file at the name, or a file with no version); else 412 precondition_failed
    *

请求体CreateNodeRequest application/json

  • parent_idstring必填
  • namestring必填
  • kindNodeKind必填
    filedir
  • if_existsstring
    When a live sibling has the same name (case-insensitive): rename creates "name (2).ext"; reuse returns the existing node of the same kind; fail (or If-None-Match: *) answers 412 precondition_failed with the existing node_id. Sync clients use reuse so concurrent creates of one path converge on one file (last save wins, both saves in its history).
    renamereusefail
    default "rename"

响应

请求示例
curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parent_id":"nod_01JD7Q3A5C7E9G1J3K5M7P9R2S","name":"A001_C003.mov","kind":"file"}'
响应示例 · 201
{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "parent_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "name": "A001_C003.mov",
  "kind": "file",
  "head_version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
  "size": 734003200,
  "mime": "video/quicktime",
  "meta_rev": 1,
  "deleted": false,
  "mtime": "2026-11-14T09:30:00Z"
}

GET/v1/spaces/{sid}/nodes/{nid}

A node now, or with as_of as it was then
Bearer 令牌

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstring必填
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

参数 · 查询

  • as_ofstring
    Read the space as it was: an RFC 3339 time, a duration ago ("-2h", "-90m"), or a journal seq. The answer's Sidespace-As-Of-Seq header names the last change included. Versions are kept until a file is deleted for good, so a past head_version_id can be downloaded as usual.

响应

请求示例
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "parent_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "name": "A001_C003.mov",
  "kind": "file",
  "head_version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
  "size": 734003200,
  "mime": "video/quicktime",
  "meta_rev": 1,
  "deleted": false,
  "mtime": "2026-11-14T09:30:00Z"
}

PATCH/v1/spaces/{sid}/nodes/{nid}

Rename and/or move (editor)
Bearer 令牌

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstring必填
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

参数 · 请求头

  • If-Matchstring
    Expected meta_rev, or a version id ("ver_…") the file must still be at; 412 precondition_failed when it differs

请求体PatchNodeRequest application/json

  • namestring
  • parent_idstring
  • if_version_idstring
    Rename or move only if the file is still at this version

响应

请求示例
curl -X PATCH "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"A001_C003.mov","parent_id":"nod_01JD7Q3A5C7E9G1J3K5M7P9R2S","if_version_id":"nod_01JD7Q3A5C7E9G1J3K5M7P9R2S"}'
响应示例 · 200
{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "parent_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "name": "A001_C003.mov",
  "kind": "file",
  "head_version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
  "size": 734003200,
  "mime": "video/quicktime",
  "meta_rev": 1,
  "deleted": false,
  "mtime": "2026-11-14T09:30:00Z"
}

DELETE/v1/spaces/{sid}/nodes/{nid}

Soft-delete a node and everything under it (editor); restorable for 30 days
Bearer 令牌

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstring必填
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

参数 · 请求头

  • If-Matchstring
    Write only if the file is still at this version ("ver_…"); else 412 precondition_failed with details.current_version_id

响应

请求示例
curl -X DELETE "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "parent_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "name": "A001_C003.mov",
  "kind": "file",
  "head_version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
  "size": 734003200,
  "mime": "video/quicktime",
  "meta_rev": 1,
  "deleted": false,
  "mtime": "2026-11-14T09:30:00Z"
}

POST/v1/spaces/{sid}/nodes/{nid}/restore

Undo a soft delete (editor)
Bearer 令牌

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstring必填
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

响应

请求示例
curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S/restore" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "id": "id",
  "space_id": "spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C",
  "parent_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "name": "A001_C003.mov",
  "kind": "file",
  "head_version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
  "size": 734003200,
  "mime": "video/quicktime",
  "meta_rev": 1,
  "deleted": false,
  "mtime": "2026-11-14T09:30:00Z"
}

POST/v1/spaces/{sid}/nodes/{nid}/rewind

Put a folder back the way it was at a moment (editor)
Bearer 令牌

Files get their old content back as a new version, deleted files come back, moved or renamed ones go back, and what was not in the folder then goes to the trash. Every step is an ordinary change, so nothing is lost and a rewind can be rewound. With dry_run nothing changes and the answer lists what would.

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstring必填
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

请求体 application/json

  • as_ofstring必填
    An RFC 3339 time, a duration ago ("-2h") or a journal seq
  • dry_runboolean
    default false

响应

请求示例
curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S/rewind" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"as_of":"as_of"}'
响应示例 · 200
{
  "as_of_seq": 1,
  "as_of_time": "2026-11-14T09:30:00Z",
  "dry_run": false,
  "changes": [
    {}
  ]
}

GET/v1/spaces/{sid}/nodes/{nid}/children

Live children ordered by name; with as_of, the children it had then (all of them, one page)
Bearer 令牌

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstring必填
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

参数 · 查询

  • cursorstring
  • limitinteger
    default 500 · ≥ 1 · ≤ 1000
  • as_ofstring
    Read the space as it was: an RFC 3339 time, a duration ago ("-2h", "-90m"), or a journal seq. The answer's Sidespace-As-Of-Seq header names the last change included. Versions are kept until a file is deleted for good, so a past head_version_id can be downloaded as usual.

响应

请求示例
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S/children" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "items": [
    {}
  ],
  "next_cursor": "next_cursor"
}

GET/v1/spaces/{sid}/nodes/{nid}/size

What a folder (or file) weighs, originals and video proxies, for an offline estimate
Bearer 令牌

参数 · 路径

  • sidstring必填
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstring必填
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

响应

请求示例
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S/size" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
响应示例 · 200
{
  "files": 1,
  "folders": 1,
  "bytes": 1,
  "videos": 1,
  "proxy_files": 1,
  "proxy_bytes": 1,
  "largest": 1
}