--- title: Spaces and files description: Create, find, update, and share files in My Space and Shared Spaces. slug: /docs/spaces updatedAt: 2026-11-02 --- Keep your files in **My Space** or work with others in **Shared Spaces**. This guide applies when your organization uses Spaces. If your dashboard still shows the earlier artifact list, continue with [publishing](/docs/publish-from-terminal). Existing document links keep working when your organization moves to Spaces. For command-line examples, use CLI 0.44.0 or later. ## Choose a destination **My Space** holds your work. Other people can open a file or folder when you give them access. **Shared Spaces** organize work for a group of people. Access can come from the Space, a containing folder, or the file itself. Open a Space from the sidebar. Then open its folders. Use **Home** to return to recent work. Use **Shared with me** to find work shared directly with you. Search finds files by name or indexed text. Results include only work you can currently access. A recent save can take time to appear in content search. Creating a Shared Space and managing its members require the relevant organization and Space permissions. Being an Owner or Admin does not give you permission to read another person's private files. ## Create a folder or file 1. Open the intended destination. 2. Use **Create** to create a folder or document, or choose a file from your computer. 3. Check the destination and who will have access. 4. Confirm the creation. A file created inside a shared folder inherits that folder's access. With a compatible command-line interface (CLI), inspect the destination before sending the file: ```bash dsp space list dsp space list-contents dsp file create --parent-id --preview dsp file create --parent-id --content-type text/markdown --idempotency-key ``` Use the file's actual media type, such as `text/html`, `text/markdown`, or `application/pdf`. Omit `--parent-id` only when you intend to create the file in My Space. For a shared destination, review the preview's audience before continuing. Keep the request key and exact file bytes until you know the result. If you lose a creation response, reuse the original request key and exact file bytes. Retry within 24 hours of the original attempt. For older uncertain attempts, check whether the file was created before retrying. After 24 hours, even the original request key can create another file. The CLI reads local files. A hosted Model Context Protocol (MCP) connection cannot read a path on your computer. It accepts small inline text or a staged file upload. See [MCP tools](/docs/mcp-server#spaces-files-and-folders). For a supported ZIP archive, choose **Import ZIP** in the Spaces dashboard. Select the intended destination, review its files and folders, and inspect the results after import. Individual files, including PDFs and Office files, can also be stored and downloaded. Uploading them does not convert them into editable documents. ## Read and update a file Open a document. Choose **Edit** when that action is available. **Save** adds a revision at the same URL. You can download other file types and replace them with an updated file. An agent should read only the source it needs. It should use the revision ID from that read as the base revision for its update: ```bash dsp file get dsp file read dsp file search dsp file edit --old "old text" --new "new text" --base-revision --idempotency-key ``` The old text must occur exactly once. For a full replacement, use `dsp file update`. Supply the source file, its media type, the explicit base revision, and a request key. Read the command's `--help` for its exact inputs. If another save changed the file, inspect that revision. Reconcile your change before retrying. Do not substitute the latest revision automatically. If you lose an update response, reuse the original request key, base revision, and inputs. Retry within 24 hours of the original attempt. For older uncertain attempts, check the current revision. Reconcile your change before retrying. To save exact source bytes, including a private or binary file: ```bash dsp file export --output ``` Choose the output path deliberately. Replacing an existing local file requires `--overwrite`. Hosted MCP returns download details instead of writing a local file. Treat its temporary download credentials as secrets. ## Rename, copy, or move files Use the matching file or folder command. Copies get new IDs. Moves retain the existing IDs. ```bash dsp file rename --name "Review notes" --idempotency-key dsp file copy --parent-id --idempotency-key dsp file move --parent-id --preview dsp file move --parent-id --if-match --idempotency-key ``` Before a move, review the preview's destination and access changes. Use the returned ETag with the same selection and destination. If the preview becomes stale, request another preview and review it before moving. Copy and move report results for each selected item. Some items can succeed while others fail. Inspect those results before deciding what to retry. If the response is uncertain, keep the original inputs and request key for recovery. ## Share a file or folder 1. Open **Share** on the file or folder. 2. Review existing access. 3. Choose the person and role. The available roles and audiences depend on the file or folder and your current permissions. Sharing a folder also affects the files and folders inside it. Inherited access remains when you remove a direct invitation. Change the source of the inherited access if you intend to remove it. Space membership and any members-only setting can still restrict access. Use `dsp file get-access ` or `dsp folder get-access ` to inspect access. Use the corresponding `share`, `change-access`, and `remove-access` commands for an authorized change. Keep the returned access reference and ETag when changing existing access. The ETag identifies the access state you read. Pass it with `--if-match` when the command requires it. An organization service key needs its own grant of access to an eligible Shared Space. It does not inherit the access of the person who created it. Public-link access alone does not authorize creating or editing files. ## Share through a group An Owner can create an organization group. Group administrators can manage membership, including adding themselves. A group's access applies through its eligible members. ```bash dsp group create --name "Reviewers" --idempotency-key dsp group add-member --email reviewer@example.com --idempotency-key dsp file share --group --role viewer --idempotency-key ``` Use `--group` instead of another recipient option. Omit `--discoverable` for group grants. Removing a group grant does not remove access from other sources. ## Give an organization key Space access A named person with current Manager access to a Shared Space can manage its organization-key grants. Owner or Admin status alone is insufficient. The key cannot grant access to itself or another key. Use the key's ID, not its secret: ```bash dsp space list-key-access dsp space allow-key --api-key --role viewer --idempotency-key dsp space change-key-access --role editor --if-match --idempotency-key dsp space revoke-key --idempotency-key ``` Migration gives eligible existing organization keys access to its Shared Space. Read-only keys receive Viewer access. Default or publish-capable keys receive Editor access. Migration grants no Manager or My Space access. New keys need an explicit grant. A root grant covers the Shared Space. A file or folder grant has narrower scope. Removing one grant leaves independent access in place. A disabled or expired key remains unusable. A replacement key needs its own grants. ## Deactivate a member An authorized Owner or Admin can preview which Shared Spaces would lose their final eligible person Manager. Review the exact member and affected Spaces. You can appoint another person through Space membership before deactivation. Replacement is optional, and keys never count as person Manager coverage. ```bash dsp member preview-deactivation dsp member deactivate --idempotency-key --confirm --json ``` The preview is advisory. Deactivation recalculates actual Manager losses. It retains membership and content and deletes the member’s personal API keys issued for that organization and removes group memberships. Organization administration does not grant private-content access. Organization service keys remain. Reactivation does not restore deleted personal keys or removed group memberships. After an uncertain response, keep the same request key and exact inputs. Retry within 24 hours. The replay reports the original committed losses, even if current Manager coverage differs. An older result without Manager-loss data means that history is unavailable. Inspect current administration rather than assuming no losses. ## Ask for access If a file link offers **Request access**, submit the role you need and an optional message. Submission does not confirm that a hidden file exists and does not grant access. Someone with the required sharing authority can approve or dismiss the request. Approval does not automatically add you to a Shared Space. Agents use `request_file_access` or `request_folder_access`. Reviewers use the matching request list and `approve_access_request` or `dismiss_access_request`. Use the same request key when retrying an unchanged request. ## Inspect history and storage Open a file's details and history to inspect saved revisions and retained storage. Revision IDs are strings, not version numbers. Copy each ID exactly when reading or downloading a historical revision. ```bash dsp file history dsp file get-revision --revision ``` Use **Keep** only when you intend to retain a revision. You cannot undo **Keep**. Before deleting a historical revision, confirm the exact revision. Delete it only when that action is available. Deleting revision bytes does not delete comments. Current, kept, or otherwise protected revisions may be ineligible. Use **Restore as a new revision** on an eligible historical revision to make its exact bytes current. Restoration adds a fresh revision at the same URL and preserves history. Confirm the historical revision and the current source revision. If someone saved newer work, inspect it. Reconcile your change before trying again. ```bash dsp file restore-revision --revision --base-revision --idempotency-key ``` ## Move work to Trash Use **Move to Trash** for a file or folder you no longer need. Restore it from Trash when that action is available. Its identity, history, and sharing remain attached. Moving a folder affects the files and folders inside it. The CLI uses `dsp file trash`, `dsp folder trash`, and their `restore` commands. Trash and Restore require a request key. Trash also requires `--confirm`. Restore needs no additional confirmation flag. For a Shared Space, `dsp space delete` requires it to be empty. `dsp space delete-with-contents` retains eligible contents for restoration. Both Space deletion commands require `--confirm` and a request key. These actions do not promise permanent erasure. ## Connect an agent safely Use the [agent setup guide](/docs/publish-with-agent) for your host. Prefer OAuth when supported. A default personal key follows its owner's current Space access. Valid existing scoped personal keys also work in Spaces. They retain their scope limits and the Member publish cap, together with the owner's current Space access. Migration preserves the key and secret. OAuth keeps its approved scope limits. Check `dsp --version`, `dsp file --help`, and the connected tool list before using Spaces commands. An older client may need an update. Ask before installing software or changing another program's configuration. Keep sign-in passwords, API keys, upload credentials, and download credentials out of chat and shared logs. If an operation is denied, use [Troubleshooting](/docs/troubleshooting). Do not switch to a broader key, change the audience, or try an older publishing command to bypass the denial. ## Review discussions Use native file selectors to read, create, reply, moderate, and manage personal comment watches. Root discussions bind to the file revision you read. Replies retain the root context. Creation retries keep the original inputs and request key for up to 24 hours. See [Review comments](/docs/comments#review-a-spaces-file).