Side Space

API reference

Files and folders

9 endpoints · Overview

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

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

Parameters · path

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

Parameters · query

  • 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.

Responses

Example request
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/paths/Ep01/Shots/A001_C003.mov" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
Example response · 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 token

Parameters · path

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

Parameters · header

  • 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
    *

Request bodyCreateNodeRequest application/json

  • parent_idstringrequired
  • namestringrequired
  • kindNodeKindrequired
    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"

Responses

Example request
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"}'
Example response · 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 token

Parameters · path

  • sidstringrequired
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstringrequired
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

Parameters · query

  • 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.

Responses

Example request
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
Example response · 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 token

Parameters · path

  • sidstringrequired
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstringrequired
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

Parameters · header

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

Request bodyPatchNodeRequest application/json

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

Responses

Example request
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"}'
Example response · 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 token

Parameters · path

  • sidstringrequired
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstringrequired
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

Parameters · header

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

Responses

Example request
curl -X DELETE "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
Example response · 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 token

Parameters · path

  • sidstringrequired
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstringrequired
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

Responses

Example request
curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S/restore" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
Example response · 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 token

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.

Parameters · path

  • sidstringrequired
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstringrequired
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

Request body application/json

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

Responses

Example request
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"}'
Example response · 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 token

Parameters · path

  • sidstringrequired
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstringrequired
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

Parameters · query

  • 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.

Responses

Example request
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S/children" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
Example response · 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 token

Parameters · path

  • sidstringrequired
    ^spc_[0-9A-HJKMNP-TV-Z]{26}$
  • nidstringrequired
    ^nod_[0-9A-HJKMNP-TV-Z]{26}$

Responses

Example request
curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S/size" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"
Example response · 200
{
  "files": 1,
  "folders": 1,
  "bytes": 1,
  "videos": 1,
  "proxy_files": 1,
  "proxy_bytes": 1,
  "largest": 1
}