Create Routing Rule

POST /functions/v1/domains/{domainId}/routing-rules

Beta. The routing rules endpoints are new and their response shapes may still change.

Creates one routing rule on a domain. The API checks rules the same way the dashboard’s Add Rule dialog does, so a rule created here behaves exactly like one created in the dashboard. The new rule takes effect right away. You need the owner or manager role on the domain. Viewers get 403 forbidden.

Always call this endpoint from a server-side environment (backend API, serverless function, build script, etc.). Never include your API key in client-side code — it will be visible to anyone inspecting your frontend.

Programmatic (API key) access requires the Pro plan and above — requests from Starter accounts return 403 plan_upgrade_required.

Request

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer hado_sk_your_key_here`
`Content-Type`	Yes	`application/json`

Path Parameters

Parameter	Type	Required	Description
`domainId`	string	Yes	The domain’s ID, from List Domains.

Body Parameters

Parameter	Type	Required	Description
`sourcePath`	string	Yes	The path to match. Must start with `/`. See Source path patterns.
`targetUrl`	string	Yes	Where matching requests go. See Targets.
`ruleType`	string	No	`redirect` (default) or `proxy`.
`redirectCode`	number	No	`301` (default, permanent) or `302` (temporary). Redirects only — sending a code with a proxy rule returns `400`.
`priority`	integer	No	Higher numbers are checked first. Default `0`.
`isActive`	boolean	No	Set to `false` to create the rule paused. Default `true`.
`notes`	string	No	Internal notes, up to 2,000 characters.

Leading and trailing whitespace is trimmed from sourcePath, targetUrl, and notes. Paths and URLs can be up to 2,048 characters.

Source path patterns

Matching ignores letter case and a trailing slash, so /About and /about/ both match a /about rule.

Pattern	Matches	Example
`/page`	That exact path	`/page` or `/page/`
`/blog/*`	The path and everything under it	`/blog`, `/blog/post-1`, `/blog/2024/jan`
`/docs/:slug`	Exactly one path segment, captured as `slug`	`/docs/intro`, but not `/docs/a/b`
`/docs/:path*`	Zero or more segments, captured as `path`	`/docs`, `/docs/a/b`
`/docs/:path+`	One or more segments, captured as `path`	`/docs/a/b`, but not `/docs`
`/shop/*/sale`	`*` in the middle matches exactly one segment	`/shop/shoes/sale`
`/gallery-*`	`*` inside a segment matches within that segment only	`/gallery-kitchen`
`/:path*/`	Only URLs that end in a slash (a trailing `/` after a pattern)	`/about/`, but not `/about`
`/page?id=42`	That exact path and query string	`/page?id=42` only

:name*, :name+, and a capturing * only work as the last segment of the pattern. Each domain can have only one rule per sourcePath. Creating a second rule with the same path returns 409.

Targets

Redirects accept either a path on your domain (/new-page) or a full http:// / https:// URL (https://other-site.com/page). You can reuse what the source matched:

Captures: put a :name or * from the source into the target to insert what it matched. For example, /old-blog/:slug → /blog/:slug sends /old-blog/hello to /blog/hello, and /:path*/ → /:path* strips the trailing slash from any URL.
Wildcards without captures: if the source ends in /* and the target has no *, the rest of the path is appended to the target. For example, /old-blog/* → /blog sends /old-blog/2024/hello to /blog/2024/hello.

The visitor’s query string is passed along to the target, except on rules whose source already includes a ?. Proxies need a full http:// or https:// URL. For security, a proxy target can’t be:

localhost or a private, internal, or link-local IP address (such as 10.x.x.x, 192.168.x.x, or 169.254.169.254)
a .internal or .local hostname
your own domain, or its www. variant, since that would loop forever

Wildcard paths are appended to proxy targets the same way as for redirects: /functions/v1/* → https://xyz.supabase.co/functions/v1 forwards /functions/v1/sitemap to https://xyz.supabase.co/functions/v1/sitemap.

How rules are matched

For each request, active rules are checked in this order, and the first match wins:

Higher priority first.
For the same priority, exact paths before patterns.
Then longer source paths before shorter ones.

So with equal priorities, /blog/featured is checked before /blog/* automatically. Raise priority when you need a rule to win outright, like a broad catch-all that should override more specific paths. A redirect whose target would be the same URL the visitor asked for is skipped, so a pattern like /:path*/ can’t cause a redirect loop.

Example Request

curl -X POST https://api.hadoseo.com/functions/v1/domains/11111111-1111-1111-1111-111111111111/routing-rules \
  -H "Authorization: Bearer hado_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sourcePath": "/old-blog/*",
    "targetUrl": "/blog",
    "redirectCode": 301,
    "notes": "Blog moved in the 2026 redesign"
  }'

Response

Success (201)

The Location response header holds the new rule’s URL, /functions/v1/domains/{domainId}/routing-rules/{ruleId}.

{
  "rule": {
    "ruleId": "cccccccc-cccc-cccc-cccc-cccccccccccc",
    "sourcePath": "/old-blog/*",
    "targetUrl": "/blog",
    "ruleType": "redirect",
    "redirectCode": 301,
    "priority": 0,
    "isActive": true,
    "notes": "Blog moved in the 2026 redesign",
    "createdAt": "2026-09-25T10:00:00.000Z",
    "updatedAt": "2026-09-25T10:00:00.000Z"
  },
  "cacheInvalidated": true
}

Field	Type	Description
`rule`	object	The new rule. See The rule object.
`cacheInvalidated`	boolean	`true` when the rule is live right away. See the note below.

The rule is always saved when you get a 201. If cacheInvalidated is false, Hado SEO couldn’t refresh your domain’s cached settings right away, so the rule may take a few minutes to start applying. You don’t need to retry.

Error Responses

Status	Body	Description
400	`{ "error": "invalid_request", "message": "..." }`	A field is missing or invalid, such as a `sourcePath` without a leading `/`, an unsupported `redirectCode`, or a blocked proxy target. The `message` explains which.
401	`{ "error": "invalid_api_key" }`	API key is missing, invalid, or revoked.
403	`{ "error": "plan_upgrade_required" }`	Programmatic access requires the Pro plan or above.
403	`{ "error": "forbidden" }`	You have `viewer` access to this domain. Creating rules needs `owner` or `manager`.
403	`{ "error": "rule_limit_reached", "limit": 25 }`	The domain already has as many rules as its owner’s plan allows.
404	`{ "error": "domain_not_found" }`	The domain in the path doesn’t exist or your account can’t access it.
409	`{ "error": "duplicate_source_path" }`	The domain already has a rule with this `sourcePath`. Update that rule instead.
429	`{ "error": "rate_limit_exceeded_monthly", "usage": 300, "limit": 300 }`	Rate limit exceeded. The code is `rate_limit_exceeded_monthly` or `rate_limit_exceeded_per_minute` — match on the `rate_limit_exceeded` prefix to catch both.

The rule limit follows the plan of the person who owns the domain. If a Starter account shared the domain with you, its Starter limit applies even if your own plan is unlimited.

Examples

Proxy a sitemap to a Supabase Edge Function

curl -X POST https://api.hadoseo.com/functions/v1/domains/11111111-1111-1111-1111-111111111111/routing-rules \
  -H "Authorization: Bearer hado_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sourcePath": "/sitemap.xml",
    "targetUrl": "https://xyz.supabase.co/functions/v1/sitemap",
    "ruleType": "proxy"
  }'

Import redirects from a list (JavaScript / Node.js)

const headers = {
  "Authorization": `Bearer ${process.env.HADOSEO_API_KEY}`,
  "Content-Type": "application/json",
};

const redirects = [
  { from: "/old-pricing", to: "/pricing" },
  { from: "/team", to: "/about#team", code: 302 },
];

for (const { from, to, code } of redirects) {
  const res = await fetch(
    `https://api.hadoseo.com/functions/v1/domains/${process.env.HADOSEO_DOMAIN_ID}/routing-rules`,
    {
      method: "POST",
      headers,
      body: JSON.stringify({
        sourcePath: from,
        targetUrl: to,
        redirectCode: code ?? 301,
      }),
    },
  );
  if (res.status === 409) {
    console.log(`skipped ${from}: a rule already exists`);
    continue;
  }
  const body = await res.json();
  if (!res.ok) throw new Error(`${from}: ${body.message ?? body.error}`);
}

Overview

Endpoints

Routing Rules

Create Routing Rule

Request

Headers

Path Parameters

Body Parameters

Source path patterns

Targets

How rules are matched

Example Request

Response

Success (201)

Error Responses

Examples

Proxy a sitemap to a Supabase Edge Function

Import redirects from a list (JavaScript / Node.js)

​Request

​Headers

​Path Parameters

​Body Parameters

​Source path patterns

​Targets

​How rules are matched

​Example Request

​Response

​Success (201)

​Error Responses

​Examples

​Proxy a sitemap to a Supabase Edge Function

​Import redirects from a list (JavaScript / Node.js)

Request

Headers

Path Parameters

Body Parameters

Source path patterns

Targets

How rules are matched

Example Request

Response

Success (201)

Error Responses

Examples

Proxy a sitemap to a Supabase Edge Function

Import redirects from a list (JavaScript / Node.js)