# Workers routes

Routes bind a Worker to URL patterns on your zone, e.g. `example.com/api/*`. Three route types exist: Custom Domains (simplest, no DNS changes), routes (pattern-based), and `workers.dev`.

## Specificity

When multiple routes could match, the most specific pattern wins. `example.com/api/records/*` beats `example.com/api/*` beats `example.com/*`. Order your thinking most-specific first.

## The failure modes

- **Overlapping routes on different Workers**: two Workers with `example.com/*` and `example.com/blog/*` is fine (specificity resolves it), but two Workers both claiming `example.com/api/*` is a conflict. Only one will serve.
- **Route without workers_dev decision**: a Worker with routes still gets a `workers.dev` subdomain unless you set `workers_dev = false`. Direct traffic to the workers.dev URL bypasses your route-scoped expectations (and your WAF, if the zone rules do not cover it).
- **Environment routes**: each `[env.*]` needs its own route keys; a staging deploy without a route does not inherit the top-level route behavior you expect.

## Custom Domains vs routes

Custom Domains attach a Worker to a hostname without DNS edits or cert management. Prefer them for new setups; use pattern routes when one Worker must serve only a path subset of a hostname.

## Checklist

- List every route across every Worker in the zone before adding a new one; check for overlaps.
- Decide `workers_dev` true/false per Worker deliberately.
- Test the actual URL, not the pattern in your head: `curl` the edge cases (`/api` vs `/api/` vs `/api/users`).