Routes

A route says: for requests matching this, forward them to this upstream — and inspect them along the way.

Minimal — match everything

version: v1alpha1

routes:
  - upstream: http://app:8000

A route with no match block matches every request.

Match by host

routes:
  - match:
      hosts: [api.example.com]
    upstream: http://api:8000

Single hostname? Use top-level host:

For a deployment with one public hostname, the simpler form is a top-level host: api.example.com and routes without match.hosts. See Hostnames & HTTPS for the three modes.

Match by path

routes:
  - match:
      paths: ["/api/*"]
    upstream: http://api:8000

Path matching supports * (single segment) and ** (any depth).

Multiple routes

routes:
  - id: api
    match:
      paths: ["/api/*"]
    upstream: http://api:8000

  - id: uploads
    match:
      paths: ["/upload/*"]
    upstream: http://uploads:8000

  - id: everything-else
    upstream: http://app:8000

Routes are evaluated most-specific first: hosts before no-host, longer paths before shorter, last route should be the catch-all.

id is optional but recommended — it appears in the audit log as route_id and in metrics as the route label.

What goes inside a route

Block	Purpose
match	What requests this route handles
upstream	Where to forward safe requests
accept	What content types, methods, and sizes to allow
rewrite	How to transform the path before forwarding
disable	Which protections to turn off on this route
detect_only	Log instead of block
openapi	Validate against an OpenAPI spec
cors	Enable CORS
response_headers	Override security headers
multipart	Configure file uploads