# Folders

> Files a team shares - on the dashboard and inside every one of its machines - and each person's own, with a Trash that keeps what was deleted for 30 days.

Files a team shares, on the dashboard and inside every one of its machines, and a folder of each person's own. Give a team a folder to view or to edit; take it away again in a moment. No key of ours is ever in a machine.

The folders you see, and a file put in your team's Design folder:

```
wm folders
wm folders put plan.md "Design:notes/plan.md"
wm folders ls "Design:notes"
```

## Team folders, and your own

An organisation's owners and admins make **team folders** on the **Folders** page. Those who decide a team's rules give each to teams, to **view** or **edit**. In your own account, your projects take the place of teams. Each person also has **My files**: owners and admins see its size, never what is in it.

A key limited to some teams reaches the folders of those teams alone: never anyone's `My files`, yours neither. `wm` reaches your `My files` with a key not limited to a team - your own account's, or an organisation owner's or admin's. A member's keys are always limited to their teams, so a member opens `My files` on the dashboard.

## In a machine

A machine has its team's folders at `~/folders`, each by name, while its holder is in the team. A view folder is read-only there. **My files shows only in machines that have only ever been yours**, since what another person left running could read it.

A machine lists at most 20,000 files and folders of one folder at once; list a larger one on the dashboard or with the API, a page at a time. Folders are for sharing files, not for building in: keep code in git, and work on the machine's own disk.

## The Trash

Deleting a file or a folder - on the dashboard, with `wm folders rm`, or in a machine - puts it in its folder's **Trash**, with everything under it, for 30 days. Put it back from there where it was (beside it, as "name (restored)", when something is there now), or delete it for good. What is in the Trash counts toward what the account keeps.

## When someone leaves

A person taken out of an organisation reaches nothing of it from that moment. Their `My files` stays 30 days more, which the organisation's owners alone may open, to take what they need, and then it goes. A file already on its way when someone leaves, or when a folder is taken from a team, finishes as it began; every call after that is refused.

Closing your account deletes its folders, and those of the organisations you were the only person in, with everything in them.

## How much, and the price

An account keeps up to 25 GB in its folders, the Trash included, and up to 250,000 files and folders; one file is at most 5 GB. A call past one of these is refused with `limit_reached` or `too_large`, and its `limit` says which ([Usage and limits](https://docs.wheelmachine.ai/limits.html)). A name is at most 255 bytes, and a path at most 1,024 bytes and 64 folders deep. An organisation uploads 16 files at once and downloads 32; a person's own account uploads 4 and downloads 8. Past that, a call is refused with `rate_limited` until one is done. A call whose bytes come or go slower than 32 KiB a second, after its first 30 seconds, ends, and none goes on past 6 hours.

Folders cost $0.03 per GB a month (£0.024 or €0.027 in an account counted in pounds or euros), counted by the day (see [Billing](https://docs.wheelmachine.ai/billing.html#what-is-taken)). When the credit runs out they turn read-only and are not charged; 30 days later their files are deleted, unless credit is added first.

## Where it is kept

Files are encrypted. Files and their names stay in the EU ([Data location](https://wheelmachine.ai/legal/data-location/)). Every change is in the account's audit: who made it, and whether from one of their machines. For a person's own folder, the audit says only the kind of change and its size, never a name in it.

## With the API

`GET /v1/folders` lists the folders you see; `PUT /v1/folders/{folder_id}/files?path=...` puts a file, with its `Content-Length`; `GET` on the same path downloads it, a `Range` too; `DELETE` puts it in the Trash. `GET /v1/folders/{folder_id}/list` lists a folder a page at a time, and its `next` says where the next page starts. A key needs `cloud:folders:read` to look and `cloud:folders:write` to change. The reference has every call.