Create a redirect

Creates a hostname-level redirect: traffic arriving on a connected hostname is forwarded to the destination you specify.

Base URL: https://api.redirhub.com/v1
Auth: Bearer token
Idempotent: No
Returns: application/json

The request

Send a JSON body to POST /redirect. url is the only required field.

# Create a redirect
curl -X POST "https://api.redirhub.com/v1/redirect" \
  -H "Authorization: Bearer $REDIRHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://acme.com/campaigns/spring",
    "forward_path": true,
    "forward_query": true
  }'

Body parameters

Field	Description
urlRequiredstring
titleoptionalstring · max 250	Human-readable label shown in the dashboard.
typeoptionalstring	Record type. List the available types with GET /shared/types.
descriptionoptionalstring · max 300	Longer description shown in the dashboard.
forward_pathoptionalboolean \| null	Append the incoming path to the destination.
forward_queryoptionalboolean \| null	Carry the incoming query string through to the destination.
utmoptionalarray<string>	UTM parameters appended to the destination.
destinationoptionalstring \| null	Where matching traffic is sent.
destinationsoptionalarray<string> \| null	Multiple targets. Pair with `destination_routing` to choose how traffic is split.
pluginsoptionalarray<string> \| null	Plugin keys to attach. List what is available with GET /shared/plugins.
is_notifyoptionalboolean	Send a notification when monitoring detects a problem.
is_switch_unbroken_destinationoptionalboolean	Move traffic to another destination when monitoring finds a broken one.
expiresoptionalstring	Timestamp after which the record stops resolving.

The response

A 200 carries the payload inside a data array — the same shape the list endpoints return, so one parser handles both.

{
  "data": [
    {
      "id": "9f2a7c31-4b8e-4a02-9d1f-0c6b7e5a1d44",
      "tld": "string",
      "host": "go.acme.com",
      "url": "https://go.acme.com/spring-sale",
      "https": true,
      "file": null,
      "destination": "https://acme.com/campaigns/spring",
      "destinations": [
        "https://acme.com/campaigns/spring"
      ],
      "destination_routing": "weighted",
      "plugins": [
        "analytics"
      ],
      "type": "link",
      "title": "Spring Sale 2026",
      "description": "Landing page for the spring campaign",
      "status": "301",
      "forward_path": true,
      "forward_query": true,
      "utm": {
        "source": "string",
        "medium": "string",
        "campaign": "string",
        "term": "string",
        "content": "string"
      },
      "monitor": "false",
      "is_notify": false,
      "is_switch_unbroken_destination": false,
      "tags": [
        "campaign",
        "q2"
      ],
      "created_by": "user@acme.com",
      "created_via": "api",
      "created_at": "2026-08-01T09:14:22Z",
      "updated_at": "2026-08-01T09:14:22Z",
      "expired_at": null
    }
  ]
}

Status codes

200

SuccessThe redirects created by this request. A single call can create several redirects at once, so the payload is always a collection.

401

UnauthenticatedUnauthenticated

422

Validation failedA field was rejected. errors lists every field with its reason.

429

Too many requestsToo many requests

482

Bad requestThe action would exceed a plan limit of the current workspace.

484

Bad requestThe workspace role of the authenticated user is too low for this action.

What usually comes next

One call is rarely the whole job. These are the endpoints most integrations reach for around this one.

Before thisGET /host What usually comes nextGET /redirect