Skip to content

Create a domain redirect

POST /api/v2/domains/{id}/redirects

Creates a URL redirect from an address on the domain to any other URL. Redirects are not DNS records: the API adds the DNS records the redirect needs for the source hostname. An existing website record for that hostname returns 409 dns_conflict instead of being overwritten. The source host must be the domain or one of its subdomains. Only sourceUrl and targetUrl are required. By default only the source address itself is redirected; send includeSubpaths: true to redirect every page. A target the rule itself would match is rejected with 400 invalid_request and errors[].code: "redirect_loop". A domain can have 10 redirects. A new rule shows status: "pending_dns" until the domain uses Hostup’s nameservers and its DNS zone is active.

Authentication: An API key with the scope write:domains. About keys and scopes

Request

Path parameters

idstringrequired
The domain ID (dom_…).

Body

sourceUrlstringrequired
The address to redirect, on the domain or one of its subdomains. Unicode and punycode hostnames are both accepted.
targetUrlstringrequired
The absolute URL to send visitors to. Unicode and punycode hostnames are both accepted.
httpStatusCodeinteger
301 or 308 for a permanent redirect, 302 or 307 for a temporary one. Default 301. One of 301, 302, 307, 308.
scopestring
Which hostnames the rule matches. exact: the source host only. root_www: the source host and www. in front of it. subdomains: every subdomain of the source host. all: every request to the domain. Default exact. One of exact, root_www, subdomains, all.
preserveQueryboolean
Keep the query string on the redirected request. Default false.
includeSubdomainsboolean
Match subdomains of the source host, like scope: "subdomains". Default false. Prefer setting scope.
includeSubpathsboolean
Redirect every page below the source address too (/contact, /en/), not only the source address. Default true when sourceUrl ends in /* or preservePath is true, otherwise false. A trailing /* is stored without the *.
preservePathboolean
Send each page to the same path on the target (/contact → target /contact). When false, every matched page goes to targetUrl as written. Needs includeSubpaths: true, which it implies when absent. Default false.
descriptionstring or null
Your own note for the rule, up to 1024 characters.

Example

POST /api/v2/domains/{id}/redirects
curl -X POST "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/redirects" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sourceUrl": "https://www.example.com",
"targetUrl": "https://example.com",
"httpStatusCode": 301,
"scope": "exact",
"description": "Redirect www to the bare domain"
}'

Responses

201 The redirect was created.

Response 201
{
"id": "redir_01hxa3b4c5d6e7f8g9h0j1k2m3",
"domainId": "dom_01hxa3b4c5d6e7f8g9h0j1k2m3",
"sourceHost": "www.example.com",
"sourcePath": null,
"sourceUrl": "https://www.example.com",
"targetUrl": "https://example.com",
"httpStatusCode": 301,
"scope": "exact",
"includeSubpaths": false,
"preservePath": false,
"preserveQuery": false,
"includeSubdomains": false,
"status": "active",
"reason": null,
"description": "Redirect www to the bare domain",
"createdAt": "2026-04-27T12:00:00.000Z",
"updatedAt": "2026-04-27T12:00:00.000Z"
}
Response fields
idstring
domainIdstring
sourceHoststring
The source host. An internationalised hostname is returned in Unicode, not punycode.
sourcePathstring or null
sourceUrlstring
The source URL. An internationalised hostname is returned in Unicode.
targetUrlstring
The target URL. An internationalised hostname is returned in Unicode.
httpStatusCodeinteger
One of 301, 302, 307, 308.
scopestring
One of exact, root_www, subdomains, all.
includeSubpathsboolean
Every page below the source address is redirected too, not only the source address itself.
preservePathboolean
Each matched page goes to the same path on the target. Only true together with includeSubpaths.
preserveQueryboolean
includeSubdomainsboolean
statusstring
One of active, pending_dns, error, disabled.
reasonstring or null
descriptionstring or null
createdAtstring or null
updatedAtstring or null

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400The body is invalid, the source host is not on the domain, the redirect would loop or the domain already has 10 redirects.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is domain_not_found.
409dns_conflict: an existing DNS record for the source hostname is in the way. invalid_request: a redirect already exists for this source URL.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.
503Redirects cannot be managed right now. Try again later.