---
title: "Attach documents to a room"
method: POST
path: "/rooms/{id}/files"
tags: ["Rooms"]
---

# Attach documents to a room

`POST /rooms/{id}/files`

## Request

- Base URL: `https://dataroom.corgi.com/api/v1`
- URL: `https://dataroom.corgi.com/api/v1/rooms/{id}/files`
- Auth: HTTP bearer

Attaches existing library documents (`documentIds`) into the room, optionally under `folderId`. Idempotent — re-adding a live file is a no-op, and re-adding a previously-removed file restores it. Because attaching a document exposes its bytes through the room, this needs `datarooms:write` PLUS a documents scope (`documents:read` suffices). Rejected with 409 when the room is frozen.

## Path parameters

- `id` string, required

## Request body

- object
  - `documentIds` string[], required
  - `folderId` string: Target room folder; omit for the room root

## Response `201`

Attached (`{ added, requested }`)

## Other responses

- `400`: No valid documents / invalid folder
- `403`: Missing the documents companion scope
- `404`: Room not found
- `409`: Room is frozen

---

[API](https://skmtc.dev/corgi/apis/dataroom-api.md) - [All operations](https://skmtc.dev/corgi/apis/dataroom-api/llms.txt) - [OpenAPI document](https://skmtc.dev/corgi/apis/dataroom-api/revisions/73f75ef04a00?raw)