Skip to main content

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.

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 and use a flexible pattern 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/url-redirects/2026-03.
  • To retrieve an individual redirect, make a GET request to /cms/url-redirects/2026-03/{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: 
curl https://api.hubapi.com/cms/url-redirects/2026-03?createdAfter=2024-01-01T00:00:00Z&limit=10 \
  --request GET \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"
The following query parameters are available:
ParameterTypeDescription
afterStringThe paging cursor token of the last successfully read resource. Available from paging.next.after in paginated responses.
archivedBooleanWhether to return only results that have been archived.
createdAfterStringOnly return redirects created after this date (ISO 8601 format).
createdAtStringOnly return redirects created on exactly this date (ISO 8601 format).
createdBeforeStringOnly return redirects created before this date (ISO 8601 format).
limitIntegerMaximum number of results per page.
sortArraySpecify the order in which the URL redirects are returned.
updatedAfterStringOnly return redirects last updated after this date (ISO 8601 format).
updatedAtStringOnly return redirects last updated on exactly this date (ISO 8601 format).
updatedBeforeStringOnly return redirects last updated before this date (ISO 8601 format).
The response includes a total count and an array of redirect objects: 
{
  "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<page_slug>.*)",
      "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/url-redirects/2026-03?after=Mg%3D%3D"
    }
  }
}

​
Retrieve a single redirect

To retrieve details for a specific redirect, make a GET request to /cms/url-redirects/2026-03/{urlRedirectId}. For example, the request below would retrieve the details for the redirect with ID 3212223134: 
curl https://api.hubapi.com/cms/url-redirects/2026-03/3212223134 \
  --request GET \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Create a redirect

To create a new URL redirect, make a POST request to /cms/url-redirects/2026-03. For example, the request below would create a permanent redirect from /old-page to /new-page: 
curl https://api.hubapi.com/cms/url-redirects/2026-03 \
  --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:
ParameterTypeDescription
routePrefix StringThe target incoming URL, path, or pattern to match for redirection.
destination StringThe location that the target URL should be redirected to if it matches the routePrefix.
redirectStyle IntegerThe type of redirect to create. Options include: 301 (permanent), 302 (temporary), or 305 (proxy).
isOnlyAfterNotFoundBooleanWhether 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.
isMatchFullUrlBooleanWhether the routePrefix should match on the entire URL, including the domain.
isMatchQueryStringBooleanWhether the routePrefix should match on the entire URL path, including the query string.
isPatternBooleanWhether the routePrefix should match based on pattern.
isProtocolAgnosticBooleanWhether the routePrefix should match both HTTP and HTTPS protocols.
isTrailingSlashOptionalBooleanWhether a trailing slash will be ignored.
precedenceIntegerUsed 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/url-redirects/2026-03/{urlRedirectId}. For example, the request below would update the redirect with ID 3212223134 to change the destination URL: 
curl https://api.hubapi.com/cms/url-redirects/2026-03/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:
ParameterTypeDescription
routePrefixStringThe target incoming URL, path, or pattern to match for redirection.
destinationStringThe location that the target URL should be redirected to if it matches the routePrefix.
redirectStyleIntegerThe type of redirect to create. Options include: 301 (permanent), 302 (temporary), or 305 (proxy).
isOnlyAfterNotFoundBooleanWhether 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.
isMatchFullUrlBooleanWhether the routePrefix should match on the entire URL, including the domain.
isMatchQueryStringBooleanWhether the routePrefix should match on the entire URL path, including the query string.
isPatternBooleanWhether the routePrefix should match based on pattern.
isProtocolAgnosticBooleanWhether the routePrefix should match both HTTP and HTTPS protocols.
isTrailingSlashOptionalBooleanWhether a trailing slash will be ignored.
precedenceIntegerUsed 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/url-redirects/2026-03/{urlRedirectId}. For example, the request below would delete the redirect with ID 3212223134: 
curl https://api.hubapi.com/cms/url-redirects/2026-03/3212223134 \
  --request DELETE \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"
A successful deletion returns a 204 No Content response with no body.
Last modified on March 30, 2026