# How to Organize Files with Folders

> A complete guide to organizing your media library on X02. Create custom folders, set default upload destinations, generate direct folder keys, enable password protection, and invite team collaborators.

Source: https://x02.me/blog/how-to-organize-files-with-folders · 2026-09-01 · X02 Team

When you start uploading dozens or hundreds of screenshots, mockups, design assets, and documents, finding what you need in a single flat gallery can quickly become chaotic.

**X02 provides a folder system** designed to keep your media organized, searchable, and easy to share. Whether you want to categorize personal screenshots, route API uploads into specific project directories, or share password-protected albums with clients, folders make managing your uploads effortless.

> [!TIP]
> **Quick Navigation:**
> * [Creating Folders & Moving Files](#part-1-the-easy-guide-for-everyone)
> * [Folder Privacy & Password Protection](#4-folder-privacy--public-sharing)
> * [Team Collaboration & Roles](#5-collaborating-with-team-members)
> * [Direct-to-Folder API Keys](#1-dedicated-folder-api-keys-direct-to-folder-uploads)
> * [Developer API & Batch Operations](#2-creating-a-folder-via-rest-api)
> * [Next Steps & Related Tutorials](#next-steps--related-tutorials)

---

## Part 1: The Easy Guide (For Everyone)

Organizing your gallery is visual, intuitive, and takes only a few seconds from your dashboard.

![Architecture Diagram](/blog-diagrams/how-to-organize-files-with-folders-1.svg)

### 1. Creating a Folder

| Where to Go | Direct Link | Action |
| :--- | :--- | :--- |
| **`Dashboard`**  **`Gallery Toolbar`**  **`New Folder (+)`** | [Open Dashboard](https://x02.me/dashboard) | Name folder & choose accent color |

1. Log in to your account at **[x02.me](https://x02.me)** and open your **Dashboard**.
2. In the gallery toolbar, click **New Folder** (or the `+` icon).
3. Enter a folder name (e.g. `Client Previews`, `Website Assets`, or `Receipts`).
4. Pick a **custom color** and **icon** to make your folder easy to identify at a glance.
5. Click **Create Folder**.

> [!NOTE]
> Free accounts can create up to **10 custom folders**, while Pro users enjoy **unlimited folders**.

---

### 2. Moving Files into Folders

X02 makes organizing files fast and flexible, whether you're moving a single file or hundreds at once:

#### Moving an Individual File
1. Find the file card in your **Dashboard Gallery**.
2. Click the **Folder icon** on the card actions bar (or click the image to open the full preview and select **Move to Folder**).
3. A modal will list all your folders. Click on your target folder (e.g. `Design Assets`).
4. The file moves instantly.

#### Batch Moving Multiple Files
1. Check the top-left checkboxes on the cards you want to organize (or click **Select All** in the toolbar).
2. Click the **Move Selected** button in the floating bulk action bar.
3. Select the destination folder from the dropdown.
4. All selected files are moved simultaneously in a single operation.

#### Moving Files Back to Root (Removing from Folder)
If you want to take a file out of a folder and return it to your main unorganized gallery:
1. Open the folder where the file currently resides.
2. Select the file(s) and click **Move to Folder**.
3. Select **All Files (Root)**.
4. The files will now appear in your general library without a folder tag.

---

### 3. Setting a Default Upload Folder
If you're currently working on a specific project, you can set a folder as your **Default Upload Destination**. 

Every new file you upload through the web browser, clipboard paste (`Ctrl+V`), or API will automatically land inside that folder without needing manual sorting.

---

### 4. Folder Privacy & Public Sharing

You decide who has access to your folder contents:

| Privacy Mode | Access Level | Best For |
|---|---|---|
| **Private (Default)** | Only visible to you and invited collaborators | Work drafts, personal receipts, private backups |
| **Public Share Link** | Accessible to anyone with the unique link (`https://x02.me/f/share-token`) | Public image galleries, community wallpaper packs |
| **Password Protected** | Accessible only after entering a password | Embargoed press kits, confidential client previews |

---

### 5. Collaborating with Team Members

You can invite other X02 users into your folders with granular permissions:

* **Admin:** Full access to manage folder settings, privacy, add/remove collaborators, upload, rename, and delete files.
* **Editor:** Can upload new files and rename existing files within the folder.
* **Viewer:** Read-only access to view and download files.

To invite a teammate, open the folder in your dashboard, click **Collaborators**, enter their username or email, and assign their role.

---

## Part 2: The Developer & Power User Guide

For engineers and automation workflows, X02 exposes REST endpoints for folder creation, batch file migration, and dedicated folder upload keys.

---

### 1. Dedicated Folder API Keys (Direct-to-Folder Uploads)

Instead of uploading a file and calling a move endpoint afterward, you can generate a **Folder-Specific Upload Key**. Any upload authenticated with this key is automatically routed directly into that folder upon ingestion.

#### Step 1: Generate the Folder Key
```bash
curl -X POST "https://x02.me/api/user/folders/FOLDER_ID/key" \
  -H "x-api-key: YOUR_PRIMARY_API_KEY"
```

**Response:**
```json
{
  "success": true,
  "apiKey": "x02_fld_key_82910fa8bc91",
  "folderId": "FOLDER_ID",
  "folderName": "Build Artifacts"
}
```

#### Step 2: Upload Directly to the Folder
```bash
curl -X POST "https://x02.me/api/upload" \
  -H "x-api-key: x02_fld_key_82910fa8bc91" \
  -F "file=@test-report.pdf"
```

---

### 2. Creating a Folder via REST API

Send a `POST` request to `/api/user/folders`:

```bash
curl -X POST "https://x02.me/api/user/folders" \
  -H "x-api-key: YOUR_X02_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Release Drops",
    "description": "Automated build logs from GitHub Actions",
    "color": "#3b82f6",
    "icon": "folder-git"
  }'
```

#### Successful JSON Response:
```json
{
  "success": true,
  "folder": {
    "id": "fld_9a82b1c",
    "name": "CI Release Drops",
    "slug": "ci-release-drops",
    "fileCount": 0,
    "createdAt": "2026-09-01T16:00:00Z"
  }
}
```

---

### 3. Moving Files via API (cURL, TypeScript, Python)

Move one or more files in a single atomic request using `PATCH /api/user/images/move`:

#### cURL Example:
```bash
curl -X PATCH "https://x02.me/api/user/images/move" \
  -H "x-api-key: YOUR_X02_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filenames": ["coverage_report.png", "benchmark.pdf"],
    "folderId": "fld_9a82b1c"
  }'
```

#### Node.js / TypeScript Example:
```typescript
async function batchMoveFiles(filenames: string[], targetFolderId: string | null, apiKey: string) {
  const response = await fetch("https://x02.me/api/user/images/move", {
    method: "PATCH",
    headers: {
      "x-api-key": apiKey,
      "Content-Type": "application/json",
      "Accept": "application/json",
    },
    body: JSON.stringify({
      filenames,
      folderId: targetFolderId, // Pass null to move back to Root
    }),
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(`Failed to move files: ${err.error}`);
  }

  const result = await response.json();
  console.log(`Successfully moved ${filenames.length} files to folder ${targetFolderId}`);
  return result;
}

// Example usage: Move files to folder
batchMoveFiles(["coverage_report.png", "benchmark.pdf"], "fld_9a82b1c", "YOUR_API_KEY")
  .catch(console.error);
```

#### Python Example:
```python
import requests

def move_files_to_folder(filenames: list, folder_id: str or None, api_key: str):
    url = "https://x02.me/api/user/images/move"
    headers = {
        "x-api-key": api_key,
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    payload = {
        "filenames": filenames,
        "folderId": folder_id  # Pass None to move back to Root
    }

    response = requests.patch(url, headers=headers, json=payload)
    if response.status_code == 200:
        print("Files moved successfully:", response.json())
        return response.json()
    else:
        print(f"Error ({response.status_code}):", response.text)
        response.raise_for_status()

# Example usage
move_files_to_folder(["coverage_report.png"], "fld_9a82b1c", "YOUR_API_KEY")
```

---

### 4. Updating Folder Privacy & Password Protection

You can toggle public sharing or set password protection on any folder via API:

```bash
curl -X PATCH "https://x02.me/api/user/folders/FOLDER_ID/privacy" \
  -H "x-api-key: YOUR_X02_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "isShareable": true,
    "isPasswordProtected": true,
    "password": "ClientSecurePass2026!"
  }'
```

---

## Next Steps & Related Tutorials

| What to learn next | Guide Link |
| :--- | :--- |
| **Send ShareX screenshots directly into folders** | [How to Integrate ShareX with X02 ](/blog/how-to-integrate-sharex-with-x02) |
| **Rename assets for clean URL paths** | [How to Rename Your Uploaded Files ](/blog/how-to-rename-uploaded-files) |
| **Update or replace files without breaking links** | [How to Replace a File Without Changing Its Link ](/blog/how-to-replace-file-without-changing-link) |
| **Master all upload methods** | [How to Upload Files to X02 ](/blog/how-to-upload-files-to-x02) |