# How to Rename Your Uploaded Files

> A complete guide on how to rename your uploaded files on X02. Turn messy screenshot names into clean, readable vanity URLs using the dashboard or developer REST API.

Source: https://x02.me/blog/how-to-rename-uploaded-files · 2026-09-01 · X02 Team

When you capture a quick screenshot or export a file from an app, it often gets a messy, auto-generated name like `Screenshot_2026-09-01_16.03.22.png` or `IMG_9042_final_v2.jpg`. 

Sharing links with chaotic filenames looks unprofessional, makes Discord embeds look untidy, and makes it almost impossible to search for files later in your library.

On **X02**, you can easily rename any file in your gallery to create clean, human-readable links (like `https://x02.me/i/dashboard-preview.png` or `https://alex.x02.me/i/resume-2026.pdf`).

> [!TIP]
> **Quick Navigation:**
> * [Renaming Files from Dashboard](#step-by-step-renaming-a-file-from-the-dashboard)
> * [Helpful Naming Rules](#helpful-naming-tips)
> * [Storage Migration & Sanitization](#1-how-renaming-works-under-the-hood)
> * [Developer API Endpoints](#2-renaming-a-file-via-curl-terminal)
> * [Role Permissions (Collaborators)](#role-based-permissions-collaborative-workspaces)
> * [Next Steps & Related Tutorials](#next-steps--related-tutorials)

---

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

Renaming your files takes just a couple of clicks from your personal dashboard.

![Architecture Diagram](/blog-diagrams/how-to-rename-uploaded-files-1.svg)

### Step-by-Step: Renaming a File from the Dashboard

| Where to Go | Direct Link | Action |
| :--- | :--- | :--- |
| **`Dashboard`**  **`Gallery`**  `[Hover File Card]` | [Open Dashboard Gallery](https://x02.me/dashboard) | Click **Rename** button |

1. **Log in** to your account on **[x02.me](https://x02.me)** and open your **Dashboard**.
2. Find the file in your **Gallery**.
3. Hover over the file card and click the **Rename** button (or open the **Media Preview Modal** and click **Rename** from the actions menu).
4. Enter your new filename (e.g. `q3-financial-chart.png`).
5. Click **Save / Rename**.

Your file is now updated, and you can copy your clean new link immediately.

---

### Helpful Naming Tips

* **Always Include the File Extension:** Make sure to keep the `.png`, `.jpg`, `.mp4`, or `.pdf` extension at the end so apps know how to display the file.
* **Use Hyphens Instead of Spaces:** Spaces are automatically turned into hyphens (e.g. `my cool screenshot.png` becomes `my-cool-screenshot.png`) so your link works cleanly on all web browsers and Discord.
* **Keep It Descriptive:** Use names that make finding the file effortless when using the gallery search bar.

---

## Part 2: The Developer & Power User Guide

For developers managing large asset libraries, bots, or CI/CD pipelines, X02 provides a dedicated REST API endpoint for programmatic file renaming.

---

### 1. How Renaming Works Under the Hood

When a rename request is sent:
1. **Sanitization & Validation:** The backend trims whitespace, replaces spaces with hyphens, sanitizes illegal path traversal characters, and validates extension formats.
2. **Atomic Storage Migration:** On cloud storage (R2/S3), an atomic `CopyObject` operation copies the file to the new key destination, followed by a `DeleteObject` on the old key to prevent data loss.
3. **MIME Type Updating:** If the extension is changed (e.g. from `.jpeg` to `.jpg`), metadata directives automatically update the `Content-Type` headers.
4. **Cache Invalidation:** The old URL is purged from edge caches so it stops serving stale data, while the new URL immediately becomes active globally.
5. **Collision Protection:** If another file with the exact same name already exists in your account, X02 returns a `409 Conflict` error to prevent accidental overwrites.

---

### 2. Renaming a File via cURL (Terminal)

Send a `PUT` request to `/api/user/images/:filename/rename` with your API key:

```bash
curl -X PUT "https://x02.me/api/user/images/old-name.png/rename" \
  -H "x-api-key: YOUR_X02_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "newFilename": "clean-release-diagram.png"
  }'
```

#### Successful JSON Response:
```json
{
  "success": true,
  "message": "File renamed successfully",
  "oldFilename": "old-name.png",
  "filename": "clean-release-diagram.png",
  "url": "https://x02.me/i/clean-release-diagram.png"
}
```

---

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

```typescript
async function renameFile(oldName: string, newName: string, apiKey: string) {
  const response = await fetch(`https://x02.me/api/user/images/${oldName}/rename`, {
    method: "PUT",
    headers: {
      "x-api-key": apiKey,
      "Content-Type": "application/json",
      "Accept": "application/json",
    },
    body: JSON.stringify({ newFilename: newName }),
  });

  if (!response.ok) {
    const errorData = await response.json();
    throw new Error(`Rename failed: ${errorData.error || response.statusText}`);
  }

  const result = await response.json();
  console.log("Renamed to:", result.url);
  return result;
}

// Example usage
renameFile("IMG_1024.png", "hero-banner.png", "YOUR_API_KEY")
  .catch(console.error);
```

---

### 4. Renaming in Python

```python
import requests

def rename_file(old_filename: str, new_filename: str, api_key: str):
    url = f"https://x02.me/api/user/images/{old_filename}/rename"
    headers = {
        "x-api-key": api_key,
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    payload = {"newFilename": new_filename}

    response = requests.put(url, headers=headers, json=payload)
    
    if response.status_code == 200:
        data = response.json()
        print(f"Renamed successfully: {data['url']}")
        return data
    else:
        print(f"Error ({response.status_code}):", response.text)
        response.raise_for_status()

# Example usage
rename_file("screencap_9182.png", "system-architecture.png", "YOUR_API_KEY")
```

---

## Role-Based Permissions (Collaborative Workspaces)

If you share media folders with team members on X02:

| Role | Can Rename Files? | Description |
|---|---|---|
| **Owner** | Yes | Full control over all assets |
| **Admin** | Yes | Can rename, replace, and organize folder contents |
| **Editor** | Yes | Can upload and rename files within the shared folder |
| **Viewer** | No | Read-only access to view and download files |

---

## Next Steps & Related Tutorials

| What to learn next | Guide Link |
| :--- | :--- |
| **Organize renamed files into folders** | [How to Organize Files with Folders ](/blog/how-to-organize-files-with-folders) |
| **Swap file content without changing the link** | [How to Replace a File Without Changing Its Link ](/blog/how-to-replace-file-without-changing-link) |
| **Connect ShareX for instant captures** | [How to Integrate ShareX with X02 ](/blog/how-to-integrate-sharex-with-x02) |
| **Explore all upload channels** | [How to Upload Files to X02 ](/blog/how-to-upload-files-to-x02) |