API reference
A data room is many documents behind one set of gates, in folders, with reading attributed per file. Build a room for a fundraise, an acquisition or a client portal, give each viewer group its own files, and freeze it when the deal closes.
Base URL https://xdocs.io/api/v1, with Authorization: Bearer xdk_… on every request. Pagination, rate limits, scopes and error codes are the same for every endpoint and are described once, in how the API behaves.
Many documents behind one set of gates, in folders, with reading attributed per file. A frozen room's contents are locked while its links keep serving them; an archived room is retired, and every link into it answers with a closed page until it is restored. A viewer group narrows a room link to some of its files and some of its readers: create one, give it members and permissions, then mint a link for it.
/api/v1/roomsrooms:readYour data rooms, most recently changed first.
Query parameters
archivedbooleanfalse for the rooms the app's room list shows, true for the archived ones. Omitted, both.limitintegercursorstringnextCursor. Opaque — pass it back unchanged.Returns
{ data: Room[], nextCursor } — id, name, description, frozenAt, archivedAt, createdAt, updatedAt
/api/v1/roomsrooms:writeAn empty room; file documents into it next.
Body (JSON)
namestringrequireddescriptionstringReturns
201 { data: Room & { folders: [], documents: [] } }
422 The plan's room ceiling has been reached./api/v1/rooms/:idrooms:readThe room with its state, its intro page and appearance, and its folders and filed documents in the order an ordinary room link shows them.
Returns
{ data: Room & { intro: { enabled, title, body, welcomeMessage }, appearance: { layout, accentColor, displayName, showSender, hasLogo, hasBanner }, folders: Folder[], documents: [{ documentId, folderId, position, title, kind, addedAt }] } } — documents in the trash are left out. The logo and banner are chosen in the app; the API says only whether there is one.
/api/v1/rooms/:idrooms:writeRename or re-describe a room, freeze or unfreeze it, archive or restore it, or change what a visitor meets before the files. None of these changes what is filed, so a frozen room accepts them.
Body (JSON)
namestringdescriptionstringfrozenbooleantrue locks the contents — nothing filed, moved or removed — while links keep serving exactly what is there.archivedbooleantrue retires the room: every link into it answers with a closed page. false puts it all back.intro{ enabled?, title?, body?, welcomeMessage? }title up to 160 characters, body Markdown up to 20,000 — and welcomeMessage, a plain note of up to 600 at the top of the contents. Merged over what is there; switching the page on needs a title or a body.appearance{ layout?, accentColor?, displayName?, showSender? }layout is list or grid; accentColor a six-digit hex such as #1f5fe0, or null for the workspace's; displayName (up to 120) is shown in place of the sender's name; showSender false hides it. Merged over what is there. A plan feature.Returns
{ data: Room & { intro, appearance, folders[], documents[] } }
422 An intro switched on with neither a title nor a body, an accent that is not a hex colour, or per-room branding on a plan without it./api/v1/rooms/:idrooms:writeTo the trash. Links into the room stop answering at once; the documents themselves are untouched.
Returns
204
409 A legal hold names this room./api/v1/rooms/:id/documentsrooms:readWhat is filed in the room, and where.
Returns
{ data: [{ documentId, folderId, position, title, kind, addedAt }] }
/api/v1/rooms/:id/documentsrooms:writeFile one of your documents. Idempotent: filing one already there moves it, which is what a sync wants.
Body (JSON)
documentIdstringrequiredfolderIdstring | nullReturns
201 { data: RoomDocument[] } — everything now filed in the room, not only this document
404 No such document, or no such folder in this room.409 The room is frozen. Unfreeze it with PATCH /rooms/:id to change its contents./api/v1/rooms/:id/documents/:documentIdrooms:writeMove a filed document between folders or along the order.
Body (JSON)
folderIdstring | nullpositioninteger 0–10,000Returns
{ data: RoomDocument[] }
404 That document is not in this room, or no such folder in it.409 The room is frozen. Unfreeze it with PATCH /rooms/:id to change its contents./api/v1/rooms/:id/documents/:documentIdrooms:writeTake a document out of the room. The document itself stays.
Returns
204
409 The room is frozen. Unfreeze it with PATCH /rooms/:id to change its contents./api/v1/rooms/:id/foldersrooms:readThe room's folders, in display order.
Returns
{ data: Folder[] } — id, dataRoomId, name, position, createdAt
/api/v1/rooms/:id/foldersrooms:writeA folder, appended after the existing ones.
Body (JSON)
namestringrequiredReturns
201 { data: Folder }
409 The room is frozen. Unfreeze it with PATCH /rooms/:id to change its contents./api/v1/rooms/:id/folders/:folderIdrooms:writeRename or reorder a folder.
Body (JSON)
namestringpositioninteger 0–10,000Returns
{ data: Folder }
409 The room is frozen. Unfreeze it with PATCH /rooms/:id to change its contents./api/v1/rooms/:id/folders/:folderIdrooms:writeRemove a folder. Its documents return to the top level rather than leaving the room.
Returns
204
409 The room is frozen. Unfreeze it with PATCH /rooms/:id to change its contents./api/v1/rooms/:id/groupsrooms:readThe room's viewer groups, oldest first.
Returns
{ data: Group[] } — id, dataRoomId, name, members (addresses and bare domains), permissions: [{ itemType, itemId, canView, canDownload, canDownloadOriginal }], links: [{ id, name, active, viewCount }], createdAt, updatedAt
/api/v1/rooms/:id/groupsrooms:writeA viewer group. It starts able to see nothing and admitting nobody, so give it members and permissions — here or afterwards — and then a link with POST /rooms/:id/groups/:groupId/links.
Body (JSON)
namestringmembersstring[]acme.com that admit everybody there.permissions{itemType, itemId, canView?, canDownload?, canDownloadOriginal?}[]itemType is folder or document, itemId one of this room's folders or filed documents. A folder grants everything filed in it that has no row of its own, and a document with canView: false inside a granted folder stays hidden. canView defaults to true; canDownload (a rendered copy, watermarked where the link says so) and canDownloadOriginal (the uploaded bytes) default to false, and neither applies to what cannot be seen. Up to 500.Returns
201 { data: Group }
422 A member that is neither an address nor a domain, or a permission naming a folder or document that is not in this room. Nothing is created.409 The room is frozen. Unfreeze it with PATCH /rooms/:id to change its contents./api/v1/rooms/:id/groups/:groupIdrooms:readOne viewer group, with its members, its permissions and its links.
Returns
{ data: Group }
/api/v1/rooms/:id/groups/:groupIdrooms:writeRename a group, or replace what it may see.
Body (JSON)
namestringpermissions{itemType, itemId, canView?, canDownload?, canDownloadOriginal?}[]itemType is folder or document, itemId one of this room's folders or filed documents. A folder grants everything filed in it that has no row of its own, and a document with canView: false inside a granted folder stays hidden. canView defaults to true; canDownload (a rendered copy, watermarked where the link says so) and canDownloadOriginal (the uploaded bytes) default to false, and neither applies to what cannot be seen. Up to 500.Returns
{ data: Group }
422 A permission naming a folder or document that is not in this room. Nothing is changed.409 The room is frozen. Unfreeze it with PATCH /rooms/:id to change its contents./api/v1/rooms/:id/groups/:groupIdrooms:writeDelete a group. Its links are switched off with it — a group link with no group behind it would have to show everything or nothing — and each that was live raises link.disabled.
Returns
204
409 The room is frozen. Unfreeze it with PATCH /rooms/:id to change its contents./api/v1/rooms/:id/groups/:groupId/membersrooms:writeAdmit people to a group. Nobody is mailed by this; POST /links/:id/invitations on one of the group's links does that, and adds the address on the way.
Body (JSON)
emailsstring[]requiredacme.com. Lowercased; entries that are neither come back in skipped.Returns
{ data: Group, added: string[], alreadyMembers: string[], skipped: string[] }
422 None of the entries is an address or a domain.409 The room is frozen. Unfreeze it with PATCH /rooms/:id to change its contents./api/v1/rooms/:id/groups/:groupId/members/:emailrooms:writeTake an address or a domain out of a group, URL-encoded in the path. They stop being admitted on its links on their next visit — unless the group also lists their domain.
Returns
{ data: Group, stillAdmitted } — stillAdmitted is true when a listed domain still lets this address in
404 Not a member of this group.409 The room is frozen. Unfreeze it with PATCH /rooms/:id to change its contents./api/v1/rooms/:id/groups/:groupId/linkslinks:writeA room link that admits only this group's members and shows only what the group was given. Takes every setting POST /links does, except that it always asks for an address — that is how membership is checked — and cannot be public.
Body (JSON)
…same as POST /linksname defaulting to “<group> link”. isPublic: true and requireEmail: false are refused. The body may be left out entirely.Returns
201 { data: Link } — with groupId set; raises link.created with groupId in its metadata
422 A public or email-less group link, a setting POST /links would refuse, or the plan's link ceiling has been reached.409 The room is frozen. Unfreeze it with PATCH /rooms/:id to change its contents.