# How to Set a Default Upload Folder

> Learn how to designate a default upload folder on X02 so all your incoming web, clipboard, ShareX, and API uploads are automatically organized into the right place.

Source: https://x02.me/blog/how-to-set-a-default-upload-folder · 2026-09-01 · X02 Team

If you are working on a specific design project, organizing screenshots for a client review, or recording clips for an upcoming video, manually moving every new upload from your main gallery into a folder takes unnecessary time.

**X02 allows you to set a Default Upload Folder.** Once set, every file you upload—whether via web drag-and-drop, clipboard paste (`Ctrl+V`), ShareX, an AI assistant over MCP, or the standard API—automatically lands straight inside your chosen folder.

> [!TIP]
> **Quick Navigation:**
> * [Why Use a Default Folder](#why-use-a-default-upload-folder)
> * [1-Click Dashboard Setup](#part-1-the-easy-guide-for-everyone)
> * [Resetting Back to Root Gallery](#resetting-back-to-root-all-files)
> * [Developer API Endpoint](#part-2-the-developer--power-user-guide)
> * [Default Folders vs. Folder Upload Keys](#default-folder-vs-folder-upload-keys)
> * [Next Steps & Related Tutorials](#next-steps--related-tutorials)

---

## Why Use a Default Upload Folder?

* **Zero Manual Sorting:** Eliminate the need to select files and click "Move to Folder" after every upload.
* **Project-Based Workflows:** Set a dedicated folder (e.g. `Client Redesign 2026`) as your default for the week, then switch it when your project finishes.
* **Cleaner Root Library:** Keep your main unorganized gallery free from clutter.
* **Works Across All Ingestion Channels:** Automatically applies to web uploads, clipboard snips, desktop tools, and developer scripts.

---

![Architecture Diagram](/blog-diagrams/how-to-set-a-default-upload-folder-1.svg)

---

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

You can set or switch your default upload folder in one click directly from your dashboard.

### Step-by-Step: Setting Your Default Folder

| Where to Go | Direct Link | Action |
| :--- | :--- | :--- |
| **`Dashboard`**  **`Gallery Toolbar`**  `[Select Folder]` | [Open Dashboard Gallery](https://x02.me/dashboard) | Click **Set as Default Folder** |

1. **Log in** to your account at **[x02.me](https://x02.me)** and open your **Dashboard**.
2. In the gallery toolbar or folder sidebar, click on the folder you want to make your default (e.g. `Work Screenshots`).
3. Click the folder options menu and select **Set as Default Upload Folder**.
4. You will see a confirmation notification, and the folder will now display a **Default** indicator.

From now on, any file you drag onto the homepage, paste via `Ctrl+V`, or capture with ShareX will be saved directly into that folder.

---

### Resetting Back to Root (All Files)

When you finish your project and want uploads to land in your root gallery again:

1. In your dashboard, click **All Files (Root)** in the folder list.
2. Click **Set as Default** (or choose *Clear Default Folder*).
3. New uploads will now land in your general gallery as normal.

---

## Part 2: The Developer & Power User Guide

For automated scripts, bots, and CI/CD pipelines, X02 allows you to programmatically read and update your default upload destination via REST API.

---

### 1. Setting Default Folder via API

Send a `POST` request to `/api/user/default-folder` with the target `folderId`:

```bash
curl -X POST "https://x02.me/api/user/default-folder" \
  -H "x-api-key: YOUR_X02_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folderId": "fld_92k8a1b"
  }'
```

#### Successful JSON Response:
```json
{
  "success": true,
  "message": "Default upload folder updated successfully",
  "defaultFolderId": "fld_92k8a1b"
}
```

---

### 2. Clearing the Default Folder (Reset to Root)

To reset your account default back to root, pass `folderId: null`:

```bash
curl -X POST "https://x02.me/api/user/default-folder" \
  -H "x-api-key: YOUR_X02_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "folderId": null
  }'
```

---

### 3. JavaScript / TypeScript Implementation (Node.js & Browser)

```typescript
async function setDefaultUploadFolder(folderId: string | null, apiKey: string) {
  const response = await fetch("https://x02.me/api/user/default-folder", {
    method: "POST",
    headers: {
      "x-api-key": apiKey,
      "Content-Type": "application/json",
      "Accept": "application/json",
    },
    body: JSON.stringify({ folderId }),
  });

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

  const result = await response.json();
  console.log("Default folder updated:", result);
  return result;
}

// Example usage: Set active project folder
setDefaultUploadFolder("fld_92k8a1b", "YOUR_API_KEY")
  .catch(console.error);
```

---

### 4. Python Implementation

```python
import requests

def set_default_folder(folder_id: str or None, api_key: str):
    url = "https://x02.me/api/user/default-folder"
    headers = {
        "x-api-key": api_key,
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    payload = {"folderId": folder_id}

    response = requests.post(url, headers=headers, json=payload)
    if response.status_code == 200:
        print("Default folder updated successfully:", response.json())
        return response.json()
    else:
        print(f"Error ({response.status_code}):", response.text)
        response.raise_for_status()

# Example usage
set_default_folder("fld_92k8a1b", "YOUR_API_KEY")
```

---

## Default Folder vs. Folder Upload Keys

X02 offers two distinct ways to route uploads into folders:

| Feature | How It Works | Best Use Case |
|---|---|---|
| **Default Upload Folder** | Changes your entire account's global default upload destination. | Temporary active projects, browser uploads, clipboard pastes. |
| **Folder Upload Keys** | Generates a unique API key hardwired to a specific folder. | Multiple ShareX profiles (e.g. Work hotkey vs Gaming hotkey) or multi-repository CI/CD drops. |

---

## Next Steps & Related Tutorials

| What to learn next | Guide Link |
| :--- | :--- |
| **Learn full folder organization and sharing** | [How to Organize Files with Folders ](/blog/how-to-organize-files-with-folders) |
| **Get your API key for automated workflows** | [How to Get an API Key ](/blog/how-to-get-an-api-key) |
| **Connect ShareX for instant desktop snips** | [How to Integrate ShareX with X02 ](/blog/how-to-integrate-sharex-with-x02) |
| **Swap uploaded files without breaking links** | [How to Replace a File Without Changing Its Link ](/blog/how-to-replace-file-without-changing-link) |