Review comments and share links

Members who are commenters or above can leave comments on a file. On video and audio a comment can be pinned to a moment (at_ms, milliseconds) or a range (until_ms); on images and frames it can mark a region (x, y, w, h as fractions of the frame, 0 to 1). Replies are one level deep: replying to a reply joins the same thread.

Read and write

curl -X POST "https://side.example.com/v1/spaces/$SPACE/nodes/$NODE/comments" \
  -H "Authorization: Bearer $SIDESPACE_TOKEN" -H "Content-Type: application/json" \
  -d '{"body": "Music too loud under the line", "at_ms": 83500, "region": {"x": 0.1, "y": 0.6, "w": 0.3, "h": 0.2}}'

for (const c of await side.comments("Film A", "/Ep01/cut.mp4")) console.log(c.at_ms, c.body, c.replies?.length);
const note = await side.addComment("Film A", "/Ep01/cut.mp4", { body: "Music too loud", at_ms: 83_500 });
await side.resolveComment("Film A", note.id);

for c in side.comments("Film A", "/Ep01/cut.mp4"):
    print(c["at_ms"], c["body"], len(c.get("replies", [])))
note = side.add_comment("Film A", "/Ep01/cut.mp4", "Music too loud", at_ms=83_500)
side.resolve_comment("Film A", note["id"])

sidespace comments "Film A" Ep01/cut.mp4                       # open threads, by timecode
sidespace comments "Film A" Ep01/cut.mp4 --add "Music too loud" --at 1:23.5
sidespace comments "Film A" Ep01/cut.mp4 --resolve cmt_…

• Tokens need comments:write to write.
• Only the author edits the text. The author or an editor resolves and reopens. The author or a manager deletes.
• A comment records the version on screen (version_id), so notes on version 3 stay readable after version 4 lands.
• The person who saved the version, and the author of a comment being replied to, get a notification.

Review links

Share a file or folder with people who have no account. With --comments (can_comment: true), they enter a name and can comment on the share page: the video pauses while they type, comments pin to the current moment, and markers sit under the timeline.

sidespace share "Film A" Ep01/cut.mp4 --comments
sidespace share "Film A" Ep01/Deliveries --upload --password "…"   # people can upload into the folder
sidespace shares "Film A"                                          # every link of the space
sidespace shares "Film A" --revoke shr_…

Over the API: POST /v1/spaces/{sid}/shares with node_id, mode (view, upload or request), can_comment, password and expires_at (the web app offers 1, 7 or 30 days). The answer has the link's url. Tokens need shares:manage. Each share counts the files people sent through it in uploads.

Request files

Ask people without an account for files (location footage, a voice-over, a client's references) with an upload request. In the web app, pick Request files… on a folder.

sidespace share "Film A" Ep03/Footage --request "Episode 3 footage" --message "MOV or MP4, one folder per camera" --days 7
sidespace shares "Film A"          # how many files each link has received

• The link shows the title, the message, who asks and the due date. It never shows what's in the folder, and the folder's files can't be opened through it.
• Senders give their name (email optional). Each person's files land in a subfolder named after them, such as Ep03/Footage/Mia Chen/a.mov; clashing names get a number, nothing is overwritten, and each version is recorded under the sender's name.
• The page uploads one file at a time with progress, takes drag and drop, and only the file that failed needs sending again.
• You get a notification for every file, with the sender's name, email and the request's title.
• After the due date (expires_at) or when revoked, the link stops taking files. It can have a password.
• Over the API, mode: "request" needs a title (up to 200 characters) and takes an optional message (up to 4,000). The MCP tool request_files does the same and makes the folder if needed.

For agents

The MCP tools list_comments, add_comment and resolve_comment let an agent read review notes, answer them and mark them done when it has made the change. Webhook events comment.created and comment.updated carry the comment, so a bot can pick up "@agent fix the color here" as it is written.