# 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.

Source: https://x02.me/blog/how-to-switch-between-short-urls-and-subdomains · 2026-09-01 · X02 Team

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](/blog/branded-file-hosting-custom-subdomains) for DNS configuration.

> [!TIP]
> **Quick Navigation:**
> * [Comparison: The Three Link Formats](#understanding-the-two-link-formats)
> * [1-Click Dashboard Switch](#part-1-the-easy-guide-for-everyone)
> * [Developer API Endpoints](#part-2-the-developer--power-user-guide)
> * [Wildcard DNS & Edge Routing Mechanics](#3-how-subdomain-routing-works-under-the-hood)
> * [Next Steps & Related Tutorials](#next-steps--related-tutorials)

---

## Understanding the Two Link Formats

| Format | Example URL | Best Used For | Plan |
|---|---|---|---|
| **Short URL** | `https://x02.me/u/A8j2P.png` | Character-limited posts on X/Twitter, discreet file drops, compact links | Free |
| **Personal Subdomain** | `https://alex.x02.me/i/A8j2P.png` | Personal portfolios, Discord communities, branded documentation, developer projects | Free |
| **Custom Domain** | `https://img.alex.dev/i/A8j2P.png` | Company branding, client-facing deliverables, full domain ownership | Pro |

---

![Architecture Diagram](/blog-diagrams/how-to-switch-between-short-urls-and-subdomains-1.svg)

---

## 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

| Where to Go | Direct Link | Action |
| :--- | :--- | :--- |
| **`Dashboard`**  **`Settings`**  **`URL Format`** | [Open Dashboard Settings](https://x02.me/dashboard) | Select **Subdomain** or **Short URL** |

1. **Log in** to your account at **[x02.me](https://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](/blog/branded-file-hosting-custom-subdomains) (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`:

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

#### JSON Response:
```json
{
  "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:
```bash
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:
```bash
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):
```bash
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)

```typescript
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

```python
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

| What to learn next | Guide Link |
| :--- | :--- |
| **Set up a Custom Domain (Pro)** | [Custom Domain Setup Guide ](/blog/branded-file-hosting-custom-subdomains) |
| **Configure ShareX to use your subdomain** | [How to Integrate ShareX with X02 ](/blog/how-to-integrate-sharex-with-x02) |
| **Organize uploads into custom folders** | [How to Organize Files with Folders ](/blog/how-to-organize-files-with-folders) |
| **Swap uploaded files without changing links** | [How to Replace a File Without Changing Its Link ](/blog/how-to-replace-file-without-changing-link) |
| **Give your uploads clean custom names** | [How to Rename Your Uploaded Files ](/blog/how-to-rename-uploaded-files) |