---
title: "POST /v1/redirects/"
method: POST
path: "/v1/redirects/"
tags: ["Redirects"]
---

# POST /v1/redirects/

`POST /v1/redirects/`

## Request

- Base URL: `https://api.redirectboss.com`
- URL: `https://api.redirectboss.com/v1/redirects/`
- Auth: API key in header `X-Api-Key`

Create a new redirect. Specify the target host by hostId or hostName.

## Request body

- object
  - `hostId` string, uuid: UUID of the host to associate this redirect with. Either hostId or hostName is required.
  - `hostName` string, hostname: Domain name of the host (e.g. "example.com"). Used as an alternative to hostId: the host will be looked up by name. Either hostId or hostName is required.
  - `matchType` 'host' | 'exact' | 'prefix', required: How to match incoming requests: "host" matches any request to the domain, "exact" matches an exact path, "prefix" matches any path starting with the given prefix
  - `path` string, http-path, nullable: Required for "exact" and "prefix" match types, forbidden for "host" match type. Must start with /
  - `destinationUrl` string, redirect-url, required: Target URL for the redirect. Must be a valid HTTP/HTTPS URL with a proper hostname.
  - `statusCode` 301 | 302 | 303 | 307, required: HTTP status code for the redirect (301=permanent, 302/303/307=temporary)
  - `preserveQueryString` boolean: Forward the original query string to the destination URL
  - `appendPath` boolean: Append the original request path to the destination URL. Useful with "host" match type to forward all paths.
  - `description` string, nullable: Optional note or label for this redirect

## Response `201`

Default Response

- object
  - `data` object, required
    - `id` string, uuid: Unique redirect identifier
    - `hostId` string, uuid: The host this redirect belongs to
    - `host` string, hostname: The domain name of the associated host
    - `matchType` 'host' | 'exact' | 'prefix': How the redirect matches incoming requests: "host" matches any request to the domain, "exact" matches an exact path, "prefix" matches any path starting with the given prefix
    - `path` string: The path to match (e.g. "/old-page"). Null for "host" match type redirects.
    - `destinationUrl` string: The target URL that matching requests are redirected to
    - `statusCode` 301 | 302 | 303 | 307: The HTTP status code used for the redirect (301=permanent, 302/303/307=temporary)
    - `preserveQueryString` boolean: Whether to forward the original query string to the redirect target
    - `appendPath` boolean: Whether to append the original request path to the redirect target
    - `description` string: Optional note or label for this redirect
    - `active` boolean: Whether the redirect is currently active. Inactive redirects do not process requests but remain fully configured and can be reactivated at any time via PATCH. To permanently remove a redirect, use DELETE instead.
    - `createdAt` string, date-time: When the redirect was created
    - `updatedAt` string, date-time: When the redirect was last updated
  - `meta` object, required
    - `requestId` string: Unique identifier for this request
    - `status` 'completed' | 'queued' | 'partial_failure': Operation status

## Other responses

- `400`: Default Response
- `404`: Default Response
- `429`: Default Response

---

[API](https://skmtc.dev/redirectboss/apis/redirectboss-api.md) · [All operations](https://skmtc.dev/redirectboss/apis/redirectboss-api/llms.txt) · [OpenAPI document](https://skmtc.dev/redirectboss/apis/redirectboss-api/revisions/0159ad2b68fa?raw)