# Read and manage Data Rooms through the API Source: https://govform.com/resources/documentation/article/33-17-api-data-rooms Topic: Govform API & MCP Read and manage retained rooms, files, participants, groups and access in one Library and selected environment. These operations do not create or change a Form or submission. ## Host, authentication and permissions Call the Builder host, `https://app.govform.com` or your private Builder host. Authenticate with the existing Library API key: `Authorization: GovformsApiKey :`, or GovformsApiHmac. Select `qa`, `staging` or `production` in the path. The environment must be configured and available. | Method and path | Required permission | Result | | --- | --- | --- | | `POST /builder/libraries/{org}/api/data-rooms/{environment}/operations` | `apiDataRoomRead` or `apiDataRoomWrite` for reads; `apiDataRoomWrite` for changes | Validated room command result | | `GET /builder/libraries/{org}/api/data-rooms/{environment}/rooms/{roomId}/files/{itemId}` | `apiDataRoomContent` plus room read/write | Authenticated file stream | | `PUT /builder/libraries/{org}/api/data-rooms/{environment}/rooms/{roomId}/files/{itemId}` | `apiDataRoomContent` plus room write | Stage a raw file; 202 means queued | Form-design and Collection permissions do not grant room access. Selecting/linking live cohort sources also requires Collection read permission. API keys are Library-scoped service identities with their explicitly granted room capabilities. OAuth MCP additionally checks the signed-in user’s current role, room assignment and separate room consent. Existing Builder write-approval policies remain in place. ## Read and change commands POST uses `Content-Type: application/json` and a command directly: ```json {"operation":"listRooms","query":{"limit":25}} ``` ```json {"operation":"createRoom","operationId":"generated-uuid","settings":{"name":"Board papers"}} ``` Read commands include `listRooms`, `getRoom`, `listItems`, `getItem`, `listPeople`, `listGroups`, `listSources`, `effectiveAccess`, `listActivity`, `previewInvitations`, `capacity` and `configuration`. The MCP command unions expose their complete input shapes. Lists default to 50 and cap at 100. Follow `nextCursor`; a bounded visibility scan may return an empty page with `continuedScan`, which is not the end of the search. Mutation commands include `createRoom`, `updateRoom`, `createFolder`, `renameItem`, `copyItems`, `cancelUpload`, `deleteItems`, `deleteRoom`, `setMember`, `setGroup`, `setItemRule`, `acknowledge`, `watch`, `leave` and `invite`. Use stable operation/item IDs for retries. Read current room or item revisions and supply `expectedRevision` where required. A stale revision returns 409; reread and review before retrying. ```json {"operation":"setMember","roomId":"room-from-read","expectedRevision":3,"email":"person@example.org","role":"reader"} ``` Saving access sends no email. `previewInvitations` returns eligible recipients and Library sign-in compatibility; `invite` explicitly queues selected recipients. `deleteItems` with `confirm:false` previews the bounded selection and descendants; confirm the intended selection before `confirm:true`. Room deletion requires its current revision and exact name. Restrictive folder rules return a confirmation preview unless `confirmed:true`. Report queued copies, uploads, email and cleanup as pending until their recorded outcomes confirm completion. Room settings accept name, description, a configured destination, managers, optional conditions, participant directory visibility, change-email enablement, active status and audit retention days. Omitted optional settings are preserved on update; name is required. Room changes save immediately in the selected environment. Library authentication, appearance and destinations keep their normal apply/deploy lifecycle. ## Upload and download file bodies PUT sends the raw file body and `X-Govform-Room-Upload`, a base64url-encoded JSON manifest: ```json {"roomId":"room-from-read","itemId":"stable-generated-uuid","name":"papers.pdf","size":12345,"sha256":"lowercase-64-character-sha256-hex","parentId":"optional-folder-id"} ``` Omit `parentId` for the room root; optional `mimeType` is also accepted. URL and manifest room/item IDs must match. Compute size and SHA-256 from the actual bytes. The server verifies the stream, capacity and security processing before an item can become Ready. A 202 is not completion; read `getItem` to observe its state. Failed upload metadata remains available through `getItem` and `listItems` to managers and the uploader under current membership, conditions and item/folder permissions. Successful file cleanup releases capacity once and retains a small failed record for seven days; `failureExpiresAt` reports its expiry. Cleanup delays retain capacity and do not start expiry. Other participants cannot see failures, and failed files cannot be opened or copied. GET streams one authorised ready file. No provider credentials, corporate sharing URLs or base64 file bodies are returned through metadata tools. ## Limits, access and usage Reader includes preview/download/print; Contributor organises permitted content. Explicit item allow-lists replace inherited rules, strongest matching access wins, and every ancestor must permit traversal. Item rules never grant room membership. Current conditions gate content handlers. Live cohort sources follow authorised contacts and fail closed when unavailable; independent grants remain. Files are up to 100 MB subject to the destination’s lower limit (Govform storage 10 MB). Copies/ZIPs cap at 100 total items including descendants and 250 MB. Rooms cap at 10,000 items, 10 folder levels and 100 groups including 20 cohort links. See [Data Rooms]() for all defaults and lifecycle behaviour. API units follow the existing account quota and exemption rules: metadata reads use 1 unit, ordinary changes 5, and bulk copy/deletion commands or binary transfers 25. Hosted room files use the existing account-wide hosted-storage allowance; processing uses the existing file-processing allowance. Count reservations include pending and deletion-pending items. Account admission retains existing census/completion semantics. ## MCP and Darcy MCP exposes `read_data_rooms` and `change_data_rooms` with `environment` and `command` (plus `org` on global OAuth). Read `govforms://docs/data-rooms`, use the discovered command schemas, and select separate Data Rooms consent when connecting. Old form-only grants do not acquire room access. Darcy exposes `readDataRooms` and `product.dataRooms`, then prepares `action:dataRoom.change` through the existing mandatory administration confirmation. Binary transfer is intentionally browser/REST-only for these agent clients.