Skip to content
RouteSeam

Domains and routes

Every redirect in RouteSeam is built from two objects: a Domain and a Route. A domain is the hostname visitors type; a route is the rule that decides where they end up. Understanding how they relate makes the dashboard and API obvious.

The Domain: the source hostname

Section titled “The Domain: the source hostname”

A domain is the source hostname you want to redirect — oldcompany.com after a rebrand, or legacy.example.com after a migration. You add it once, point one DNS record at RouteSeam, and RouteSeam verifies DNS, issues an HTTPS certificate automatically, and starts redirecting.

A few rules about domains:

  • Each hostname can be claimed exactly once across all of RouteSeam. This prevents one customer from hijacking another’s hostname.
  • A domain has a lifecycle — it moves from pending_dns through verification and TLS provisioning to active. See domain lifecycle for the full state machine.
  • A domain only redirects once it is active. Before that, it is onboarding or in a failed state.

The Route: the redirect rule

Section titled “The Route: the redirect rule”

A route is the redirect rule attached to a domain. When you add a domain through the dashboard, RouteSeam creates its route for you. A route has these settings:

  • Destination URL — where traffic goes. Must be a valid http:// or https:// URL. RouteSeam validates it whenever you set it and rejects destinations that would create a redirect loop — see redirect loops below.
  • Status code — the HTTP response code: 301, 302, 307, or 308. The default is 308 Permanent Redirect, which is permanent, cacheable, and preserves the request method. For guidance on choosing, see redirect types.
  • Preserve path — on by default. With it on, old.com/products/widget redirects to new.com/products/widget. With it off, every request lands on the destination root.
  • Preserve query — on by default. With it on, old.com/products?id=123 keeps its ?id=123 through the redirect, so tracking parameters such as utm_source survive.
  • Include www — a setting on the domain rather than the route. When you add example.com, RouteSeam offers Include www.example.com so both example.com and www.example.com redirect, without creating a second domain object.
  • Enabled / disabled — a route can be switched off without deleting it. A disabled route is removed from the edge configuration; traffic to that hostname then gets no redirect until you re-enable it.

Redirect loops

Section titled “Redirect loops”

RouteSeam refuses to save a destination that would send visitors in a circle. It checks by following the chain of RouteSeam domains forward from the destination you entered, up to ten hops, and rejecting it if the chain comes back to the domain you are editing. That covers:

  • a domain pointing at itself
  • two domains pointing at each other
  • longer chains — a.com → b.com → c.com → a.com
  • www. forms of a domain that has Include www turned on, since those resolve to the same domain

A few deliberate exceptions:

  • A destination on a non-standard port, like https://example.com:8443, is not treated as a loop. RouteSeam only serves ports 80 and 443, so that address genuinely goes somewhere else.
  • If a chain already loops but does not include the domain you are editing, your change is allowed. You are not blocked by someone else’s configuration unless it would actually break your domain.
  • Turning on Include www is itself checked, because it can complete a loop without any destination changing: www.example.com starts resolving to your domain, which may be exactly where another domain was already pointing.

The check looks at how domains are configured, not at what is currently live. A domain that is still pending DNS, or a route that is switched off, still counts — hostnames are unique across RouteSeam, so that redirect would start working the moment the domain activates. This means you cannot create a loop now that surprises you later, and re-enabling a route can never introduce one.

When a destination is rejected, the message names only your own domain, never anyone else’s.

Section titled “The second kind of route: short links”

The route described above is a catch-all: it answers every request to the domain, whatever the path. A domain can also carry any number of short links, which are routes of a second kind. A short link answers one exact path — go.example.com/docs — and sends visitors to a destination of its own.

Short links share the route settings that make sense for them: a destination URL, a status code, preserve query, and enabled or disabled. Two things differ:

  • The default status code is 302, not 308. A short link’s destination is expected to change, and a cached permanent redirect cannot be taken back from a visitor’s browser.
  • They can expire. A short link may carry a future expiry date, after which it stops resolving.

Preserve path has no meaning for a short link: it matches a single path and always sends visitors to the destination exactly as entered.

Every short link counts as a route against your plan’s route limit, the same as a catch-all does. For creating and managing them, see short links.

How a request flows through them

Section titled “How a request flows through them”

A visitor’s request to https://old.com/products/widget?id=123 is answered at the edge in constant time: RouteSeam looks up the hostname old.com, then looks for a short link at the exact requested path. An exact path match beats the catch-all. With no short link at that path, the domain’s catch-all answers instead, applying preserve-path and preserve-query — for example:

HTTP/1.1 308 Permanent Redirect
Location: https://new.com/products/widget?id=123

The lookup happens from an in-memory routing table at the edge — there is no database query on the request path. See architecture for how the configuration gets there.

A route that is disabled, or a short link that is past its expiry, is left out of that table entirely. Requests to a lapsed short link’s path therefore fall through to the domain’s catch-all, or get a 404 if the domain has no active catch-all.

Editing a route

Section titled “Editing a route”

You can change the destination, status code, or path/query options at any time from the domain detail page. Changes are published to the edge as a new configuration version and are live within seconds. See domain lifecycle for what happens when you disable or delete a domain entirely.

Section titled “Related pages”