> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: d3f04f14-0a9d-4d47-8a39-0dd792ff5b0c
---
# URL redirects API
> Use the URL redirects API to manage URL redirects for HubSpot-hosted pages
export const PostmanCard = ({title, collectionId}) => {
return
} />
;
};
export const Tag = ({children, type = 'default', className = ''}) => {
return
{children}
;
};
export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
URL redirects allow you to redirect traffic from a HubSpot-hosted page to any URL. In HubSpot, you can also update [URL redirects in bulk](https://knowledge.hubspot.com/domains-and-urls/bulk-upload-url-redirects) and use a [flexible pattern redirect](https://knowledge.hubspot.com/domains-and-urls/set-up-a-flexible-pattern-url-redirect) to dynamically update the structure of URLs.
## Retrieve redirects
You can retrieve URL redirects either individually by ID or by retrieving all redirects:
* To retrieve all redirects, make a `GET` request to `/cms/v3/url-redirects`.
* To retrieve an individual redirect, make a `GET` request to `/cms/v3/url-redirects/{urlRedirectId}`.
### Retrieve all redirects
When retrieving all redirects, you can filter and sort the returned results using query parameters.
For example, the following request would retrieve the first 10 redirects created after January 1, 2024:
```shell wrap theme={null}
curl https://api.hubapi.com/cms/v3/url-redirects?createdAfter=2024-01-01T00:00:00Z&limit=10 \
--request GET \
--header "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
The following query parameters are available:
| Parameter | Type | Description |
| --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `after` | String | The paging cursor token of the last successfully read resource. Available from `paging.next.after` in paginated responses. |
| `archived` | Boolean | Whether to return only results that have been archived. |
| `createdAfter` | String | Only return redirects created after this date (ISO 8601 format). |
| `createdAt` | String | Only return redirects created on exactly this date (ISO 8601 format). |
| `createdBefore` | String | Only return redirects created before this date (ISO 8601 format). |
| `limit` | Integer | Maximum number of results per page. |
| `sort` | Array | Specify the order in which the URL redirects are returned. |
| `updatedAfter` | String | Only return redirects last updated after this date (ISO 8601 format). |
| `updatedAt` | String | Only return redirects last updated on exactly this date (ISO 8601 format). |
| `updatedBefore` | String | Only return redirects last updated before this date (ISO 8601 format). |
The response includes a `total` count and an array of redirect objects:
```json theme={null}
{
"total": 2,
"results": [
{
"id": "3212223134",
"createdAt": "2017-07-24T17:24:09.141Z",
"updatedAt": "2017-07-24T17:24:09.141Z",
"routePrefix": "http://test.hs-sites.com/(?P.*)",
"destination": "http://www.example.online/{page_slug}",
"redirectStyle": 301,
"isOnlyAfterNotFound": true,
"isMatchFullUrl": true,
"isMatchQueryString": false,
"isPattern": false,
"isTrailingSlashOptional": true,
"isProtocolAgnostic": true,
"precedence": 3
}
],
"paging": {
"next": {
"after": "Mg%3D%3D",
"link": "https://api.hubspot.com/cms/v3/url-redirects?after=Mg%3D%3D"
}
}
}
```
### Retrieve a single redirect
To retrieve details for a specific redirect, make a `GET` request to `/cms/v3/url-redirects/{urlRedirectId}`.
For example, the request below would retrieve the details for the redirect with ID `3212223134`:
```shell wrap theme={null}
curl https://api.hubapi.com/cms/v3/url-redirects/3212223134 \
--request GET \
--header "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
## Create a redirect
To create a new URL redirect, make a `POST` request to `/cms/v3/url-redirects`.
For example, the request below would create a permanent redirect from `/old-page` to `/new-page`:
```shell wrap theme={null}
curl https://api.hubapi.com/cms/v3/url-redirects \
--request POST \
--header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"routePrefix": "/old-page",
"destination": "/new-page",
"redirectStyle": 301
}'
```
The following request body parameters are available:
| Parameter | Type | Description |
| ------------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `routePrefix` Required | String | The target incoming URL, path, or pattern to match for redirection. |
| `destination` Required | String | The location that the target URL should be redirected to if it matches the `routePrefix`. |
| `redirectStyle` Required | Integer | The type of redirect to create. Options include: `301` (permanent), `302` (temporary), or `305` (proxy). |
| `isOnlyAfterNotFound` | Boolean | Whether the URL redirect mapping should apply only if a live page on the URL isn't found. If `false`, the URL redirect mapping will take precedence over any existing page. |
| `isMatchFullUrl` | Boolean | Whether the `routePrefix` should match on the entire URL, including the domain. |
| `isMatchQueryString` | Boolean | Whether the `routePrefix` should match on the entire URL path, including the query string. |
| `isPattern` | Boolean | Whether the `routePrefix` should match based on pattern. |
| `isProtocolAgnostic` | Boolean | Whether the `routePrefix` should match both HTTP and HTTPS protocols. |
| `isTrailingSlashOptional` | Boolean | Whether a trailing slash will be ignored. |
| `precedence` | Integer | Used to prioritize URL redirection. If a given URL matches more than one redirect, the one with the lower precedence will be used. |
## Update a redirect
To update an existing URL redirect, make a `PATCH` request to `/cms/v3/url-redirects/{urlRedirectId}`.
For example, the request below would update the redirect with ID `3212223134` to change the destination URL:
```shell wrap theme={null}
curl https://api.hubapi.com/cms/v3/url-redirects/3212223134 \
--request PATCH \
--header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"destination": "/updated-page"
}'
```
The following request body parameters are available:
| Parameter | Type | Description |
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `routePrefix` | String | The target incoming URL, path, or pattern to match for redirection. |
| `destination` | String | The location that the target URL should be redirected to if it matches the `routePrefix`. |
| `redirectStyle` | Integer | The type of redirect to create. Options include: `301` (permanent), `302` (temporary), or `305` (proxy). |
| `isOnlyAfterNotFound` | Boolean | Whether the URL redirect mapping should apply only if a live page on the URL isn't found. If `false`, the URL redirect mapping will take precedence over any existing page. |
| `isMatchFullUrl` | Boolean | Whether the `routePrefix` should match on the entire URL, including the domain. |
| `isMatchQueryString` | Boolean | Whether the `routePrefix` should match on the entire URL path, including the query string. |
| `isPattern` | Boolean | Whether the `routePrefix` should match based on pattern. |
| `isProtocolAgnostic` | Boolean | Whether the `routePrefix` should match both HTTP and HTTPS protocols. |
| `isTrailingSlashOptional` | Boolean | Whether a trailing slash will be ignored. |
| `precedence` | Integer | Used to prioritize URL redirection. If a given URL matches more than one redirect, the one with the **lower** precedence will be used. |
## Delete a redirect
To delete an existing URL redirect, make a `DELETE` request to `/cms/v3/url-redirects/{urlRedirectId}`.
For example, the request below would delete the redirect with ID `3212223134`:
```shell wrap theme={null}
curl https://api.hubapi.com/cms/v3/url-redirects/3212223134 \
--request DELETE \
--header "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
A successful deletion returns a `204 No Content` response with no body.