Read and manage Data Rooms through the API
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 <key-id>:<key-secret>, 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:
{"operation":"listRooms","query":{"limit":25}}{"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.
{"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:
{"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.