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.

By X02 Team · 2026-09-01 · Tutorial, File Management, API, Productivity, Developer Tools

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
• Helpful Naming Rules
• Storage Migration & Sanitization
• Developer API Endpoints
• Role Permissions (Collaborators)
• Next Steps & Related Tutorials

Part 1: The Easy Guide (For Everyone)

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

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

1. Log in to your account on 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:

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:

{
  "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)

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

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:

Next Steps & Related Tutorials

Read this article on X02