Moving and organizing

Folders are where documents live; see Folders, tags, and stars for what each of the three concepts is for, and Roots and folders for My documents, General and shared roots. This page is about changing the tree once you have one. The tools and endpoints below work in My documents by default and take root to work in General or a shared root, where they need edit on the folder.

The rule that makes all of this safe: a document's URL never changes. The address is built from an immutable slug, not from the folder path, so you can move and rename freely.

Moving a document

A document is in exactly one folder. Moving it changes that one thing.

• In the app: drag the document onto a folder in the sidebar or onto a folder tile, or use the Move action on the document and pick the destination. Moving to the root is allowed.
• From an agent: move_doc(doc_id, folder). Pass "" for the root. The destination is created if it does not exist. Add root to move the document into another root. Prompt: "Move the onboarding checklist into HR/Onboarding."
• REST: PATCH /api/docs/{id} with {"folder": "HR/Onboarding"}; "" moves to the root; add "root" to change roots.

Moving a document from My documents into General or a shared root hands it to the root: it then belongs to the root, not to you. Who may move what between roots is on Roots and folders.

The response is the document object with its new folder. Everything else about it (URL, visibility, tags, version, retention) is untouched. Moving does not create a new version.

Creating a folder

You usually do not need to. Publishing or moving into a path creates every missing level. Create one explicitly when you want an empty folder to exist now, for example to set up a structure before an agent fills it in.

• In the app: New folder in the sidebar or inside the current folder.
• From an agent: create_folder(path). Prompt: "Create Customers/Acme and Customers/Globex."
• REST: POST /api/folders with {"path": "Customers/Acme"}.

Path rules (characters, depth, length) are listed on Folders, tags, and stars.

Renaming or moving a folder

Renaming a folder and moving it to a different parent are the same operation: the folder gets a new path, and everything under it comes along.

• In the app: Rename on the folder, or drag the folder onto another folder.
• From an agent: rename_folder(path, new_path). Prompt: "Rename Clients to Customers", or "Move Customers/Acme under Archive" (the agent calls rename_folder("Customers/Acme", "Archive/Acme")).
• REST: PATCH /api/folders with {"path": "Clients", "new_path": "Customers"}.

What moves: every document directly in the folder, every subfolder and its documents, and any star pointing at the folder or a subfolder. Document URLs do not change.

What is refused: renaming the root, an empty new path, and moving a folder inside itself (Customers to Customers/Old). Renaming to a path that already exists merges the two trees.

Deleting a folder

Deleting a folder never deletes documents.

• An empty folder (no documents, no subfolders) is deleted outright.
• A folder with contents is refused unless you force it. With force, its documents and subfolders move up one level to the parent (or to the root if it was a top-level folder), and then the folder is removed. A star on the folder itself follows to the new path, or is dropped if that would be the root.

How to do it:

• In the app: Delete on the folder; the app tells you when the folder is not empty and what will happen to its contents.
• From an agent: delete_folder(path) for an empty folder, delete_folder(path, force=true) to move the contents to the parent first. Prompt: "Get rid of the Scratch folder but keep the documents."
• REST: DELETE /api/folders?path=Scratch or DELETE /api/folders?path=Scratch&force=true.

If you want the documents gone as well, delete them first; see Deleting.

What happens to links

Nothing. A link to a document is https://fermiumusercontent.app/d/<slug>/ (or the same path on your custom domain). Folders are not part of it, so:

• Moving a document keeps every link, embed and bookmark working.
• Renaming or deleting a folder keeps every link to every document that was in it working.
• Relative links inside a document (img/chart.png, style.css) keep working because they are relative to the document, not to the folder.
• Links between documents use the target's URL, which did not change. See Links between documents.

Retention is also unaffected: moving is not an update, so it does not reset the expiry clock and does not create a version.

Tags when you reorganize

Tags are attached to the document, not to the folder, so they come along with it. A document tagged customer-facing in Clients/Acme is still tagged customer-facing in Customers/Acme, and the tag view still lists it.

Shared documents in the browser

The place for documents that belong to the team is General or a shared root. Documents that stay in someone's My documents can still be listed for the team (listing: team): they show up in every member's My documents view, tinted as shared, in the folder their owner keeps them in. Folders in My documents are per account, so the folder appears in a member's tree only because a shared document lives there, tinted the same way, and counts only the documents they may open. The Shared with me filter narrows the browser to those documents and folders. If you want workspace members to find something, list it for the team and tag it; a tag lists it wherever it lives.