How to Switch Between Short URLs and Subdomain URLs

Learn how to choose between compact short URLs (x02.me/u/...) and personalized subdomain links (username.x02.me/i/...) for your uploads on X02.

By X02 Team · 2026-09-01 · Tutorial, Custom Domain, Branding, API, Developer Tools

When you upload a file to X02, you can choose how your public links look. Depending on where you share your content, you might want a compact, minimalist link for fast chat messages or a branded, personalized link that highlights your username.

X02 gives every registered user the ability to switch between URL styles:

1. Short URLs (https://x02.me/u/...): Compact, neutral, and minimalist.
2. Personal Subdomain URLs (https://username.x02.me/i/...): Branded and customized to your account handle.
3. Custom Domain URLs (https://img.yourbrand.com/i/...): A domain you personally own — Pro plan only. See the Custom Domain Setup Guide for DNS configuration.

[!TIP] Quick Navigation:

• Comparison: The Three Link Formats
• 1-Click Dashboard Switch
• Developer API Endpoints
• Wildcard DNS & Edge Routing Mechanics
• Next Steps & Related Tutorials

Understanding the Two Link Formats

Part 1: The Easy Guide (For Everyone)

Switching your default link format takes only one click from your dashboard.

Step-by-Step: Changing Your URL Format

1. Log in to your account at x02.me and open your Dashboard.
2. Click Settings in the navigation bar.
3. Find the URL Format / Subdomain section.
4. Select your preferred style:
   • Subdomain: Generates https://yourusername.x02.me/i/...
   • Short URL: Generates https://x02.me/u/...
   • Custom Domain: Generates https://your-domain.com/i/... — only shown once you've added and verified a domain in the Custom Domain section (Pro plan required).
5. Click Save Preferences.

Your selected style will now be applied automatically to all future uploads made via the web browser, clipboard paste, ShareX, MCP, and the API.

What Happens to Your Existing Uploads?

[!NOTE] Zero Broken Links: Changing your URL format preference only affects the link copied for new uploads. All previously shared files continue to resolve on both domains without interruption.

Part 2: The Developer & Power User Guide

For developers building third-party integrations, bots, or custom uploaders, X02 exposes REST endpoints to read and update your URL format settings programmatically.

1. Checking Your Current URL Format via API

Send a GET request to /api/user/subdomain:

curl -X GET "https://x02.me/api/user/subdomain" \
  -H "x-api-key: YOUR_X02_API_KEY"

JSON Response:

{
  "success": true,
  "data": {
    "format": "subdomain",
    "subdomainUrl": "https://alex.x02.me/i/ABCD.png",
    "standardUrl": "https://x02.me/u/ABCD.png",
    "customDomainActive": false,
    "customDomainUrl": null
  }
}

2. Updating Your URL Format via API

Send a POST request to /api/user/subdomain with the desired format:

Set to Subdomain Mode:

curl -X POST "https://x02.me/api/user/subdomain" \
  -H "x-api-key: YOUR_X02_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "subdomain" }'

Set to Short URL Mode:

curl -X POST "https://x02.me/api/user/subdomain" \
  -H "x-api-key: YOUR_X02_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "short" }'

Set to Custom Domain Mode (Pro plan, domain must already be verified):

curl -X POST "https://x02.me/api/user/subdomain" \
  -H "x-api-key: YOUR_X02_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "custom" }'

[!NOTE] Setting format to "custom" before a domain is added and verified via /api/user/custom-domain has no effect on new uploads — X02 automatically falls back to subdomain format until your domain shows as Active.

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

async function setUrlFormatPreference(format: "subdomain" | "short", apiKey: string) {
  const response = await fetch("https://x02.me/api/user/subdomain", {
    method: "POST",
    headers: {
      "x-api-key": apiKey,
      "Content-Type": "application/json",
      "Accept": "application/json",
    },
    body: JSON.stringify({ format }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Failed to update URL format: ${error.error}`);
  }

  const result = await response.json();
  console.log("Updated URL format preference:", result);
  return result;
}

// Example usage: Switch to clean short URLs
setUrlFormatPreference("short", "YOUR_API_KEY")
  .catch(console.error);

4. Python Implementation

import requests

def update_url_format(format_type: str, api_key: str):
    url = "https://x02.me/api/user/subdomain"
    headers = {
        "x-api-key": api_key,
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    payload = {"format": format_type}

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

# Example usage
update_url_format("subdomain", "YOUR_API_KEY")

3. How Subdomain Routing Works Under the Hood

When a request arrives at https://username.x02.me/i/file.png:

1. Wildcard DNS Resolution: Cloudflare Anycast DNS captures *.x02.me traffic and routes it to X02's edge gateway.
2. Wildcard Edge SSL: Automatic TLS/SSL certificates secure all tenant subdomains with zero manual certificate provisioning.
3. Tenant Context Extraction: The edge server parses the Host header, extracts the username prefix, validates tenant ownership, and routes the asset directly from object storage (R2/S3).
4. Isolated Brand Experience: Viewers receive direct, high-speed media delivery branded with your personal handle.

Next Steps & Related Tutorials

Read this article on X02