Redirects

On this page, we'll dive into the different redirects endpoints you can use to manage redirects programmatically. We'll look at how to query, create, update, and delete redirects.

The redirect model

The redirect model contains all the information about your redirects.

Properties

Name
uuid
Type
string
Description
Unique identifier for the redirect.
Name
source_host
Type
string
Description
The host where the incoming request arrives. For example, if you want to redirect requests from old-domain.com, this would be "old-domain.com".
Name
match_path
Type
string
Description
The path pattern to match for redirecting. Default value is "*" which matches all paths. Can contain letters, numbers, dashes, underscores, forward slashes, and an optional trailing asterisk for prefix matching.
Name
destination_url
Type
string
Description
The URL where matching requests will be redirected to. This must be a valid URL where you want to send the traffic.
Name
redirect_type
Type
string
Description
The HTTP status code to use for the redirect. Can be one of:
- permanent (HTTP code 301) - Default value, tells browsers and search engines that the redirect is permanent
- found (HTTP code 302) - Indicates a temporary redirect
Name
preserve_path
Type
boolean
Description
Whether to preserve the original request path when redirecting. Default is true. When enabled, the original path will be appended to the destination URL.
Name
preserve_query_string
Type
boolean
Description
Whether to preserve the query string when redirecting. Default is true. When enabled, the original query parameters will be appended to the destination URL.
Name
active
Type
boolean
Description
Whether the redirect is currently active. Default is true. Inactive redirects won't redirect any traffic.
Name
created_at
Type
timestamp
Description
The date and time when the redirect was created.
Name
updated_at
Type
timestamp
Description
The date and time when the redirect was last updated.

GET

/api/v1/accounts/:account_uuid/redirects

List redirects

This endpoint allows you to retrieve a paginated list of all redirects belonging to an account. By default, 20 redirects are shown per page.

Optional attributes

Name
source_host
Type
string
Description
Filter redirects by source host.
Name
page
Type
integer
Description
The page number to retrieve. Default value is 1.
Name
per_page
Type
integer
Description
The number of items to retrieve per page. Default value is 20.
Name
sort
Type
string
Description
The field to sort by. Available fields: created_at, updated_at, source_host.

Request

GET

/api/v1/accounts/:account_uuid/redirects

curl -G https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/redirects \
  -H "Authorization: Bearer {token}" \
  -d source_host="old-domain.com" \
  -d page=1

Response

{
  "data": [
    {
      "uuid": "redirect_52069e63",
      "source_host": "old-domain.com",
      "match_path": "*",
      "destination_url": "https://new-domain.com",
      "redirect_type": "permanent",
      "preserve_path": true,
      "preserve_query_string": true,
      "active": true,
      "created_at": "2024-01-14T13:19:42.193+01:00",
      "updated_at": "2024-01-14T13:19:42.193+01:00",
      "account_uuid": "account_3f43d84c"
    },
    {
      "uuid": "redirect_d3ba54e7",
      // ...
    }
  ],
  "pagination": {
    "page": 1,
    "count": 42
  }
}

POST

/api/v1/accounts/:account_uuid/redirects

Create

This endpoint allows you to create a new redirect.

Required attributes

Name
source_host
Type
string
Description
The host where the incoming request arrives. This must be a valid hostname.
Name
destination_url
Type
string
Description
The URL where matching requests will be redirected to.

Optional attributes

Name
match_path
Type
string
Description
The path pattern to match. Default is "*" which matches all paths. Can contain letters, numbers, dashes, underscores, forward slashes, and an optional trailing asterisk for prefix matching.
Name
redirect_type
Type
string
Description
The HTTP status code to use for the redirect. Can be one of:
- permanent (HTTP code 301) - Default value, tells browsers and search engines that the redirect is permanent
- found (HTTP code 302) - Indicates a temporary redirect
Name
preserve_path
Type
boolean
Description
Whether to preserve the original path. Default is true.
Name
preserve_query_string
Type
boolean
Description
Whether to preserve query parameters. Default is true.
Name
active
Type
boolean
Description
Whether the redirect should be active. Default is true.

Request

POST

/api/v1/accounts/:account_uuid/redirects

curl https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/redirects \
  -H "Authorization: Bearer {token}" \
  -d source_host="old-domain.com" \
  -d destination_url="https://new-domain.com"

Response

{
  "uuid": "redirect_52069e63",
  "source_host": "old-domain.com",
  "match_path": "*",
  "destination_url": "https://new-domain.com",
  "redirect_type": "permanent",
  "preserve_path": true,
  "preserve_query_string": true,
  "active": true,
  "created_at": "2024-01-14T13:19:42.193+01:00",
  "updated_at": "2024-01-14T13:19:42.193+01:00",
  "account_uuid": "account_3f43d84c"
}

PUT

/api/v1/accounts/:account_uuid/redirects/:redirect_uuid

Update

This endpoint allows you to update an existing redirect.

Optional attributes

Name
source_host
Type
string
Description
The host where the incoming request arrives.
Name
destination_url
Type
string
Description
The URL where matching requests will be redirected to.
Name
match_path
Type
string
Description
The path pattern to match.
Name
redirect_type
Type
string
Description
The HTTP status code to use for the redirect. Can be one of:
- permanent (HTTP code 301) - Default value, tells browsers and search engines that the redirect is permanent
- found (HTTP code 302) - Indicates a temporary redirect
Name
preserve_path
Type
boolean
Description
Whether to preserve the original path.
Name
preserve_query_string
Type
boolean
Description
Whether to preserve query parameters.
Name
active
Type
boolean
Description
Whether the redirect should be active.

Request

PUT

/api/v1/accounts/:account_uuid/redirects/:redirect_uuid

curl -X PUT https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/redirects/:redirect_uuid \
  -H "Authorization: Bearer {token}" \
  -d destination_url="https://updated-domain.com"

Response

{
  "uuid": "redirect_52069e63",
  "source_host": "old-domain.com",
  "match_path": "*",
  "destination_url": "https://updated-domain.com",
  "redirect_type": "permanent",
  "preserve_path": true,
  "preserve_query_string": true,
  "active": true,
  "created_at": "2024-01-14T13:19:42.193+01:00",
  "updated_at": "2024-01-14T13:25:16.421+01:00",
  "account_uuid": "account_3f43d84c"
}

GET

/api/v1/accounts/:account_uuid/redirects/:redirect_uuid

Retrieve

This endpoint allows you to retrieve a redirect by providing its UUID. Refer to the list at the top of this page to see which properties are included with redirect objects.

Request

GET

/api/v1/accounts/:account_uuid/redirects/:redirect_uuid

curl https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/redirects/:redirect_uuid \
  -H "Authorization: Bearer {token}"

Response

{
  "uuid": "redirect_52069e63",
  "source_host": "old-domain.com",
  "match_path": "*",
  "destination_url": "https://new-domain.com",
  "redirect_type": "permanent",
  "preserve_path": true,
  "preserve_query_string": true,
  "active": true,
  "created_at": "2024-01-14T13:19:42.193+01:00",
  "updated_at": "2024-01-14T13:19:42.193+01:00",
  "account_uuid": "account_3f43d84c"
}

DELETE

/api/v1/accounts/:account_uuid/redirects/:redirect_uuid

Delete

This endpoint allows you to delete a redirect.

Request

DELETE

/api/v1/accounts/:account_uuid/redirects/:redirect_uuid

curl -X DELETE https://app.saascustomdomains.com/api/v1/accounts/:account_uuid/redirects/:redirect_uuid \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "Redirect redirect_52069e63 (old-domain.com) deleted."
}

Error responses

When the API encounters an error, it will respond with an appropriate HTTP status code and a JSON object containing error details.

Example error responses

400 Bad Request - Invalid source_host

{
  "error": "Source host is not a valid hostname",
  "error_code": "source_host_invalid"
}

400 Bad Request - Invalid match_path

{
  "error": "Match path can only contain letters, numbers, dashes, underscores and an optional trailing asterisk",
  "error_code": "match_path_invalid"
}

400 Bad Request - Source host taken

{
  "error": "Source host is already taken",
  "error_code": "source_host_taken"
}

404 Not Found

{
  "error": "Redirect redirect_52069e63 not found.",
  "error_code": "not_found"
}