Retitle, relink, invite into, set the work status of or archive a work session
Changes the title, description, linked spaces, participants or work status, or archives the session. workStatus (active, ready_for_review, done) needs only work_session:comment, but done must come from a person: an org API key, a trigger delivery is 403 work_status_needs_person, and so is archive: true from any of them, since archiving marks the work done. Archiving sets done, a reopen active, and a new agent turn moves it back to active. Authorization: work_session:comment on the session, OR space:contribute on one of its linked spaces; a desk session is writable only by its owner. Any denial is 404. spaces, removeHumans and archive need MORE than that: they are the owner’s (work_session:manage, spec §8.1), so a participant or a space contributor gets 403 forbidden on those three fields and keeps title, description and addHumans. Every id in spaces is re-checked as the caller exactly as POST /workspace/sessions checks spaceIds: a me:* desk the session is not ALREADY on is 400 cannot_target_desk (moving a session onto a desk would hide it from its own opener) and a space that does not exist or the caller cannot contribute to is 404, so a relay can never move a session somewhere its owner loses it. Each entry is { spaceId, access } (access defaults to commit) or a bare id string, and spaces replaces the whole set, so it needs at least one entry — a session with no space cannot host a turn, and an empty array left it un-mentionable with no way back. fileIds replaces the working set the same way — every id is resolved as the caller (404 for an unknown or unreadable one) and [] empties it, so a session whose set carries a file nobody can read is repairable instead of permanently un-mentionable. A relink is checked against the working set it MOVES: every file the session already runs on must live in the new turn space, so a spaces patch that would leave the session un-mentionable is 404 — send fileIds in the same call ([] empties the set) to move and refill at once. The body is STRICT: an unknown key is 400 validation_failed, never a 200 that changed nothing. Every id in addHumans must be an active member of the caller’s organization: an id from another organization, or one that names nobody, is 404, so the roster never lists a person who could not open the session. addHumans also grants each member the work-session-participant FGA role, and removeHumans revokes it — agents are never FGA subjects (a turn runs as the human who mentioned it). A DESK session cannot be shared: the gate authorizes it by identity alone, so addHumans on one is 400 cannot_share_desk — relink it to a real space first. (A session opened with no spaceIds lands on the desk, so this is the default create path’s sharing story.)
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Request
The session’s working set, replaced wholesale. Every id must exist and be readable by the caller; [] empties the set.
Whether the WORK is done, which only people decide. status stays the derived state of the turns.