Create a short link

One request puts a short link live on a hostname you already control. host is the only required field — everything else refines how the link behaves.

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

The request

Send a JSON body to POST /link. host is the only required field.

# Create a short link
curl -X POST "https://api.redirhub.com/v1/link" \
  -H "Authorization: Bearer $REDIRHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "go.acme.com",
    "alias": "spring-sale",
    "destination": "https://acme.com/campaigns/spring",
    "title": "Spring Sale 2026",
    "forward_path": true,
    "forward_query": true,
    "tags": [
      "campaign",
      "q2"
    ]
  }'

Body parameters

Field	Description
hostRequiredstring · max 100	A hostname already connected to the workspace. See List hostnames.
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.
aliasoptionalstring · max 30	The path segment that follows the hostname.
destination_routingoptionalstring	How traffic is distributed across `destinations`.
statusoptionalinteger	The HTTP status code used for the redirect response.
tagsoptionalarray<string>	Freeform labels. Filter on them with `filter[tags]`.

Aliases are claimed per hostname. If the alias is already in use the API answers 422 with the field in errors. Ask for an available one first with POST /recommendation/alias, or omit alias entirely.

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",
      "host": "go.acme.com",
      "alias": "spring-sale",
      "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 short links created by this request. The payload is always a collection, even for a single link.

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