> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hadoseo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Routing Rules

> Set up redirects and proxies for your domain

## Overview

Routing rules let you control how URLs are handled on your domain. You can create redirects to send visitors to new URLs, or proxies to transparently route requests to external services.

<Info>
  Starter plans include up to 5 routing rules. All other plans include unlimited routing rules.
</Info>

## Accessing Routing Rules

1. Go to your [Dashboard](https://hadoseo.com/dashboard)
2. Select your domain
3. Click the **Routing Rules** tab

## Rule Types

### Redirects

Redirects send visitors and bots to a different URL. The browser's address bar changes to show the new URL.

**Use redirects when:**

* Moving content to a new URL
* Consolidating duplicate pages
* Fixing broken links
* Migrating from an old domain

**Redirect Status Codes:**

| Code    | Name               | Use Case                                                    |
| ------- | ------------------ | ----------------------------------------------------------- |
| **301** | Permanent Redirect | Content has permanently moved. Passes SEO value to new URL. |
| **302** | Found (Temporary)  | Temporary redirect. Original URL keeps SEO value.           |

<Tip>
  Use **301** for most permanent URL changes. It tells search engines to transfer link equity to the new URL.
</Tip>

### Proxies

Proxies route requests to an external service without changing the browser's URL. Visitors see your domain, but content comes from elsewhere.

**Use proxies when:**

* Serving your sitemap from a backend function (e.g., Supabase Edge Functions)
* Routing public API endpoints to another service
* Using a headless CMS for public content
* Serving public assets from an external origin

**Example:** Proxy `/sitemap.xml` to a Supabase Edge Function while keeping your domain.

<Warning>
  Proxies are designed for **public endpoints only**. Authorization headers and cookies are not forwarded to proxy targets for security reasons. Authenticated API calls through proxy rules will fail.
</Warning>

## Creating Rules

### Add a Single Rule

1. Click **Add Rule**
2. Select rule type (Redirect or Proxy)
3. Enter the source path (e.g., `/old-page`)
4. Enter the destination (new URL or proxy target)
5. For redirects, select the status code
6. Click **Save**

### Source Path Patterns

| Pattern       | Matches    | Example                          |
| ------------- | ---------- | -------------------------------- |
| `/page`       | Exact path | `/page` only                     |
| `/blog/*`     | Wildcard   | `/blog/post-1`, `/blog/2024/jan` |
| `/docs/:slug` | Parameter  | `/docs/intro`, `/docs/api`       |

### Examples

**Redirect old URL to new URL:**

```
Source: /old-pricing
Destination: /pricing
Type: 301 Redirect
```

**Redirect with wildcard:**

```
Source: /blog/2023/*
Destination: /archive/2023/
Type: 301 Redirect
```

**Proxy to external API:**

```
Source: /api/cms/*
Destination: https://your-cms.com/api/
Type: Proxy
```

## Bulk Import (CSV)

Import multiple rules at once using a CSV file.

### CSV Format

```csv theme={null}
source,destination,type,status_code,notes
/old-page,/new-page,redirect,301,Renamed page
/legacy/*,/current/,redirect,301,Legacy URL cleanup
/api/external/*,https://api.example.com/,proxy,,External API
```

| Column        | Required      | Description           |
| ------------- | ------------- | --------------------- |
| `source`      | Yes           | Source path pattern   |
| `destination` | Yes           | Target URL or path    |
| `type`        | Yes           | `redirect` or `proxy` |
| `status_code` | For redirects | 301 or 302            |
| `notes`       | No            | Optional description  |

### Import Steps

1. Click **Import CSV**
2. Download the template (optional)
3. Upload your CSV file
4. Review imported rules
5. Click **Save All**

### Export Rules

Export your existing rules to CSV:

1. Click **Export CSV**
2. Download opens automatically
3. Edit in spreadsheet software
4. Re-import to update

## Rule Priority

Rules are processed in order from top to bottom. The first matching rule is applied.

**To reorder rules:**

1. Drag and drop rules in the list
2. More specific rules should come before wildcards
3. Click **Save Order** after reordering

**Example ordering:**

```
1. /blog/featured     → /featured-posts    (specific)
2. /blog/*            → /articles/         (wildcard)
```

If the wildcard came first, `/blog/featured` would never match.

## Validation

Hado SEO validates rules to prevent common mistakes:

### Redirect Validation

* Destination URL must be valid
* Can't redirect to the same URL (infinite loop)
* Source pattern must be valid

### Proxy Validation

* Destination must be a full URL (https\://...)
* Can't proxy to your own domain (circular proxy)
* Source pattern must be valid

## Limitations

| Plan    | Routing Rules |
| ------- | ------------- |
| Starter | Up to 5       |
| Pro     | Unlimited     |
| Growth  | Unlimited     |
| Agency  | Unlimited     |

## Best Practices

<AccordionGroup>
  <Accordion title="Use 301 for permanent changes" icon="arrow-right">
    When content permanently moves, use 301 redirects. This:

    * Transfers SEO link equity to the new URL
    * Tells search engines to update their index
    * Provides the best user experience
  </Accordion>

  <Accordion title="Keep redirect chains short" icon="link">
    Avoid redirect chains (A → B → C → D). Each hop:

    * Adds latency
    * May lose SEO value
    * Can confuse search engines

    **Bad:** `/page1` → `/page2` → `/page3` → `/final`

    **Good:** `/page1` → `/final`
  </Accordion>

  <Accordion title="Use wildcards carefully" icon="asterisk">
    Wildcards are powerful but can over-match:

    **Too broad:** `/*` matches everything

    **Better:** `/old-section/*` matches only that section

    Test wildcards before deploying.
  </Accordion>

  <Accordion title="Document your rules" icon="note-sticky">
    Use the notes field to explain why each rule exists:

    * When it was added
    * Why it's needed
    * Related ticket/issue numbers

    Future you will thank you.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Redirect not working" icon="circle-question">
    **Check:**

    * Is the source path correct? (case-sensitive)
    * Is there a more specific rule matching first?
    * Did you save the rule?
    * Is DNS configured for your domain?
  </Accordion>

  <Accordion title="Proxy returning errors" icon="circle-question">
    **Check:**

    * Is the destination URL accessible?
    * Is the destination URL using HTTPS?
    * Does the destination allow requests from your domain?
    * Is there a circular proxy (proxying back to yourself)?
  </Accordion>

  <Accordion title="Rules not in expected order" icon="circle-question">
    Rules are processed top-to-bottom. Reorder them:

    1. More specific paths first
    2. Wildcards last
    3. Click Save Order after reordering
  </Accordion>
</AccordionGroup>

## Use Cases

### Domain Migration

Moving from `old-domain.com` to `new-domain.com`:

```csv theme={null}
source,destination,type,status_code
/,https://new-domain.com/,redirect,301
/*,https://new-domain.com/,redirect,301
```

### Vanity URLs

Create short, memorable URLs:

```csv theme={null}
source,destination,type,status_code
/go,/getting-started,redirect,302
/pricing,/plans-and-pricing,redirect,301
/demo,https://calendly.com/your-demo,redirect,302
```

### API Proxying

Route API calls to a backend service:

```csv theme={null}
source,destination,type,status_code
/api/v1/*,https://api.your-backend.com/v1/,proxy,
/graphql,https://your-graphql.com/graphql,proxy,
```

<CardGroup cols={2}>
  <Card title="Dashboard Overview" icon="gauge" href="/dashboard/overview">
    Return to dashboard
  </Card>

  <Card title="Domain Settings" icon="gear" href="/dashboard/domain-settings">
    Configure other domain settings
  </Card>
</CardGroup>