API reference

Versions

8 endpoints · Overview

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

Change byte ranges of a file and save it as a new version (editor)

Bearer token

Partial writes (ADR 0033). Each op replaces delete bytes at at with text (or base64 bytes): a write in place, an insert (delete 0), a removal (no data), or an append (at = the file's size). Offsets are in the version the edits are made against: the head, or if_version_id / If-Match, which must still be the head (else 412 precondition_failed). Ranges may not overlap; at most 10,000 ops and 4 MiB of new data at a time. truncate then cuts the result. Only the chunks around an edit are new; the rest of the file is reused.

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

Request bodyEditRequest application/json

if_version_idstring
The version the offsets are in; must still be the head
opsEditOp[]
≤ 10000 items
› 4 fields
- atinteger (int64)required
  Byte offset in the old version
  ≥ 0
- deleteinteger (int64)
  Bytes removed there
  default 0 · ≥ 0
- textstring
  Inserted there, as UTF-8
- base64string
  Inserted there, as bytes (instead of text)
truncateinteger (int64)
Cut the result to this many bytes
≥ 0

Responses

201
Saved
CommitVersionResponse
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S/edits" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"if_version_id":"nod_01JD7Q3A5C7E9G1J3K5M7P9R2S","ops":[{}],"truncate":1}'

Example response · 201

{
  "version": {
    "id": "id",
    "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "seq": 3,
    "size": 734003200,
    "mime": "video/quicktime",
    "manifest_hash": "manifest_hash",
    "author": {},
    "device_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "base_version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
    "superseded_version_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "client_mtime": "2026-11-14T09:30:00Z",
    "created_at": "2026-11-14T09:30:00Z",
    "label": "Client cut",
    "labeled_by": "labeled_by",
    "labeled_at": "2026-11-14T09:30:00Z"
  },
  "node": {
    "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"
  },
  "superseded": {
    "version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
    "author": {}
  }
}

POST/v1/spaces/{sid}/upload-sessions

Ask which chunks the block gateway is missing and get a put ticket (editor)

Bearer token

Parameters · path

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

Request bodyUploadSessionRequest application/json

hashesHash[]required
≤ 20000 items

Responses

200
Session
UploadSession
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/upload-sessions" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hashes":["9f2c4e6a8b0d2f4a6c8e0b2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a"]}'

Example response · 200

{
  "missing": [
    "missing"
  ],
  "ticket": "ticket",
  "blockgw_url": "blockgw_url",
  "expires_at": "2026-11-14T09:30:00Z"
}

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

Version history, newest first

Bearer token

Parameters · path

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

Responses

200
Versions
object
› Show fields
- itemsVersionInfo[]
  › 15 fields
  - idstringrequired
  - node_idstringrequired
  - seqintegerrequired
    1-based per node
  - sizeintegerrequired
  - mimestring | nullrequired
    required
  - manifest_hashHashrequired
    ^[0-9a-f]{64}$
  - authorUserrequired
    › 4 fields
    idstringrequired
    emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
    display_namestringrequired
    kindstringrequired
    humanagent
  - device_idstring | nullrequired
    required
  - base_version_idstring | nullrequired
    required
  - superseded_version_idstring | nullrequired
    Head this save replaced although it was not its base
    required
  - client_mtimeTimestamp | anyrequired
  - created_atTimestamprequired
  - labelstring
    The name someone gave this version ("Client cut"), unique per file; absent if none
  - labeled_bystring
  - labeled_atTimestamp
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S/versions" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "items": [
    {
      "id": "id",
      "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "seq": 3,
      "size": 734003200,
      "mime": "video/quicktime",
      "manifest_hash": "manifest_hash",
      "author": {},
      "device_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "base_version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
      "superseded_version_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
      "client_mtime": "2026-11-14T09:30:00Z",
      "created_at": "2026-11-14T09:30:00Z",
      "label": "Client cut",
      "labeled_by": "labeled_by",
      "labeled_at": "2026-11-14T09:30:00Z"
    }
  ]
}

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

Commit a new version (editor). Last save wins.

Bearer token

Always accepted when every chunk exists. When base_version_id is not the current head, the new version still becomes head, superseded names the replaced head, and that version's author is notified (version.superseded). Committing to a deleted node restores it. Missing chunks answer 409 missing_chunks.

To save only if nobody saved in between, send If-Match: "ver_…" (or if_version_id) with the version you read; to save only into a file that has no version yet, send If-None-Match: * (or if_new: true). Either answers 412 precondition_failed with details.current_version_id when it does not hold, and nothing is saved.

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
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 bodyCommitVersionRequest application/json

base_version_idstring | nullrequired
required
manifestManifestrequired
› 3 fields
- algostringrequired
  fastcdc-v1
- sizeintegerrequired
- chunksChunkRef[]required
  › 3 fields
  - hashHashrequired
    ^[0-9a-f]{64}$
  - offsetintegerrequired
  - lenintegerrequired
mimestring
client_mtimeTimestamp
if_version_idstring
Save only if the file is still at this version (same as If-Match); else 412 precondition_failed
if_newboolean
Save only if the file has no version yet (same as If-None-Match: *)

Responses

201
Committed
CommitVersionResponse
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/nodes/nod_01JD7Q3A5C7E9G1J3K5M7P9R2S/versions" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"base_version_id":"ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T","manifest":{"algo":"fastcdc-v1","size":734003200,"chunks":[]}}'

Example response · 201

{
  "version": {
    "id": "id",
    "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "seq": 3,
    "size": 734003200,
    "mime": "video/quicktime",
    "manifest_hash": "manifest_hash",
    "author": {},
    "device_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "base_version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
    "superseded_version_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "client_mtime": "2026-11-14T09:30:00Z",
    "created_at": "2026-11-14T09:30:00Z",
    "label": "Client cut",
    "labeled_by": "labeled_by",
    "labeled_at": "2026-11-14T09:30:00Z"
  },
  "node": {
    "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"
  },
  "superseded": {
    "version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
    "author": {}
  }
}

POST/v1/spaces/{sid}/versions/{vid}/restore

Copy an old version as the new head (editor)

Bearer token

Parameters · path

sidstringrequired
^spc_[0-9A-HJKMNP-TV-Z]{26}$
vidstringrequired
^ver_[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

201
Committed
CommitVersionResponse
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/versions/ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T/restore" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 201

{
  "version": {
    "id": "id",
    "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "seq": 3,
    "size": 734003200,
    "mime": "video/quicktime",
    "manifest_hash": "manifest_hash",
    "author": {},
    "device_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "base_version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
    "superseded_version_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "client_mtime": "2026-11-14T09:30:00Z",
    "created_at": "2026-11-14T09:30:00Z",
    "label": "Client cut",
    "labeled_by": "labeled_by",
    "labeled_at": "2026-11-14T09:30:00Z"
  },
  "node": {
    "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"
  },
  "superseded": {
    "version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
    "author": {}
  }
}

PUT/v1/spaces/{sid}/versions/{vid}/label

Name a version ("Client cut"), or clear its name with "" (editor)

Bearer token

A name belongs to one version of a file at a time (case does not matter), so naming another version moves it. Journals version.labeled.

Parameters · path

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

Request body application/json

labelstringrequired
≤ 60 chars

Responses

200
The version
VersionInfo
4xx/5xx
Error
Error

Example request

curl -X PUT "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/versions/ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T/label" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Client cut"}'

Example response · 200

{
  "id": "id",
  "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "seq": 3,
  "size": 734003200,
  "mime": "video/quicktime",
  "manifest_hash": "manifest_hash",
  "author": {
    "id": "id",
    "email": "[email protected]",
    "display_name": "display_name",
    "kind": "human"
  },
  "device_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "base_version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
  "superseded_version_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
  "client_mtime": "2026-11-14T09:30:00Z",
  "created_at": "2026-11-14T09:30:00Z",
  "label": "Client cut",
  "labeled_by": "labeled_by",
  "labeled_at": "2026-11-14T09:30:00Z"
}

GET/v1/spaces/{sid}/versions/{vid}/compare/{other}

What differs from one version to another (of one file or two files in the space)

Bearer token

Parameters · path

sidstringrequired
^spc_[0-9A-HJKMNP-TV-Z]{26}$
vidstringrequired
^ver_[0-9A-HJKMNP-TV-Z]{26}$
otherstringrequired
The version to compare with (B); vid is A

Responses

200
The differences
VersionCompare
4xx/5xx
Error
Error

Example request

curl "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/versions/ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T/compare/other" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN"

Example response · 200

{
  "a": {
    "id": "id",
    "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "seq": 3,
    "size": 734003200,
    "mime": "video/quicktime",
    "manifest_hash": "manifest_hash",
    "author": {},
    "device_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "base_version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
    "superseded_version_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "client_mtime": "2026-11-14T09:30:00Z",
    "created_at": "2026-11-14T09:30:00Z",
    "label": "Client cut",
    "labeled_by": "labeled_by",
    "labeled_at": "2026-11-14T09:30:00Z"
  },
  "b": {
    "id": "id",
    "node_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "seq": 3,
    "size": 734003200,
    "mime": "video/quicktime",
    "manifest_hash": "manifest_hash",
    "author": {},
    "device_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "base_version_id": "ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T",
    "superseded_version_id": "nod_01JD7Q3A5C7E9G1J3K5M7P9R2S",
    "client_mtime": "2026-11-14T09:30:00Z",
    "created_at": "2026-11-14T09:30:00Z",
    "label": "Client cut",
    "labeled_by": "labeled_by",
    "labeled_at": "2026-11-14T09:30:00Z"
  },
  "same_content": false,
  "size_delta": 1,
  "bytes": {
    "shared": 1,
    "only_a": 1,
    "only_b": 1,
    "shared_ratio": 0.5
  },
  "media": [
    {
      "field": "field",
      "a": "a",
      "b": "b"
    }
  ],
  "sidecars": [
    {
      "namespace": "x-acme.qc",
      "change": "added",
      "fields": []
    }
  ],
  "renditions": {
    "key": [
      "string"
    ]
  }
}

POST/v1/spaces/{sid}/download-tickets

Get a get-ticket and the manifest for a version (or one of its renditions)

Bearer token

Parameters · path

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

Request bodyDownloadTicketRequest application/json

version_idstringrequired
renditionstring
e.g. thumb, or proxy (the server-made 720p H.264 stream of a video)
streamboolean
A ticket for a player: lasts a viewing session (6 h) instead of minutes

Responses

200
Ticket
DownloadTicket
4xx/5xx
Error
Error

Example request

curl -X POST "https://side.example.com/v1/spaces/spc_01JD7Q2M8X4V6N0R3T5W9Y1B2C/download-tickets" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version_id":"ver_01JD7Q4B6D8F0H2J4L6N8Q0S3T"}'

Example response · 200

{
  "ticket": "ticket",
  "manifest": {
    "algo": "fastcdc-v1",
    "size": 734003200,
    "chunks": []
  },
  "blockgw_url": "blockgw_url",
  "expires_at": "2026-11-14T09:30:00Z"
}