Skip to navigation

Retitle, relink, invite into, set the work status of or archive a work session

View as Markdown

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

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

sessionIdstringRequired

Request

This endpoint expects an object.
titlestringOptional1-200 characters
descriptionstringOptional<=8000 characters
spaceslist of strings or objectsOptional
addHumanslist of stringsOptional
removeHumanslist of stringsOptional
fileIdslist of stringsOptional

The session’s working set, replaced wholesale. Every id must exist and be readable by the caller; [] empties the set.

archivebooleanOptional
workStatusenumOptional

Whether the WORK is done, which only people decide. status stays the derived state of the turns.

Allowed values:

Response

The updated work session.
dataobject

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error