Create a hostname

POST /host is part of the Hostnames group. Its parameters and response shape below are generated from the live OpenAPI document.

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

The request

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

# Create a hostname
curl -X POST "https://api.redirhub.com/v1/host" \
  -H "Authorization: Bearer $REDIRHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "go.acme.com",
    "https_requested": true,
    "short_links_enabled": true,
    "connection_mode": "managed"
  }'

Body parameters

Field	Description
hostRequiredstring	The hostname to connect, e.g. `go.example.com`. Wildcards are not accepted here.
https_requestedoptionalboolean	Whether the platform should issue and renew an SSL certificate for this hostname and accept HTTPS traffic on it. Defaults to `true` for a hostname that is being connected for the first time, and leaves an already connected one untouched.
short_links_enabledoptionalboolean	Whether this hostname may be used to create new short links. QR codes are generated from short links, so this also controls QR code creation on this hostname. Existing links and QR codes continue to resolve when disabled.
connection_modeoptionalstring	How a hostname reaches RedirHub. `managed`: its DNS points to us and the edge serves it once its DNS check passes (NS, CNAME or TXT). `integration`: its DNS stays where it is; the customer's own CDN, app or CMS downloads the rules and redirects, and the first answer of its check path with the workspace's check token proves the workspace owns it (IntegrationHealth::checkMany(), HostOwnership::activateIntegration()). Both are probed by the same hostname check (system:dns-check, BulkVerifyDns), on the same schedule. The edge never serves an integration's links (EdgeRecordQuery). Both proofs end in `active` and `dns_correct`, so the mode never decides who a hostname belongs to. An integration has no grace period; one switched back to `managed` gets the grace period of a newly added hostname where no other workspace holds it (HostOwnership::switchConnectionMode()). managedintegration

The response

A 200 returns the record as JSON.

{
  "host": "go.acme.com",
  "domain": "string",
  "correct": true,
  "connection_mode": "string",
  "status": "sync_stopped",
  "integration": "string",
  "default_require": "ip",
  "require": [
    "string"
  ],
  "current": [
    "string"
  ],
  "errors": [
    {
      "scope": "string",
      "code": "string",
      "message": "The given data was invalid.",
      "updated_at": "2026-08-01T09:14:22Z"
    }
  ],
  "counts": [
    "string"
  ],
  "https_requested": true,
  "force_https": true,
  "ssl_renews_at": "string",
  "ssl_issued_at": "string",
  "connected_via": "string",
  "connected_at": "string",
  "dns_verified_at": "string",
  "created_by": {
    "id": "9f2a7c31-4b8e-4a02-9d1f-0c6b7e5a1d44",
    "name": "Acme"
  },
  "short_links_enabled": true,
  "public": true,
  "notice": "string",
  "checked_at": "string",
  "created_at": "2026-08-01T09:14:22Z",
  "updated_at": "2026-08-01T09:14:22Z"
}

Status codes

200

SuccessThe hostname that is now connected to the workspace.

401

UnauthenticatedUnauthenticated

409

ConflictA request with the same Idempotency-Key is still running

422

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

429

Too many requestsToo many requests

484

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