URL Redirects

URL redirects let you map old paths to new ones, preserving SEO when product handles, collection slugs, or page URLs change. Hydra automatically resolves redirect chains - if A redirects to B and B later redirects to C, the A redirect is updated to point directly to C.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/redirects	Publishable / Secret	List redirects
GET	/v1/redirects/lookup	Publishable / Secret	Look up a redirect by path
POST	/v1/redirects	Secret	Create a redirect
DELETE	/v1/redirects/{id}	Secret	Delete a redirect

---

List redirects

GET /v1/redirects

Returns a paginated list of all redirects for the store. Used by the admin panel to manage redirects.

Query parameters

Parameter	Type	Default	Description
limit	integer	25	Results per page (1–100)
cursor	string	-	Pagination cursor from a previous response
sort	string	created_at	Sort field: created_at, updated_at, title
order	string	desc	Sort direction: asc, desc
fields	string	-	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/redirects?limit=10 \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "rdr_abc123def456ghij",
			"old_path": "/classic-t-shirt",
			"new_path": "/premium-t-shirt",
			"resource_type": "product",
			"resource_id": "prod_abc123",
			"created_at": "2026-06-15T10:30:00Z",
			"updated_at": "2026-06-15T10:30:00Z"
		},
		{
			"id": "rdr_xyz789klm012nopq",
			"old_path": "/summer-sale",
			"new_path": "/collections/summer-2026",
			"resource_type": "collection",
			"resource_id": "col_def456",
			"created_at": "2026-05-01T14:00:00Z",
			"updated_at": "2026-05-01T14:00:00Z"
		}
	],
	"pagination": {
		"cursor": "eyJ0IjoiMjAyNi...",
		"has_more": false,
		"total": 2
	}
}

---

Look up a redirect

GET /v1/redirects/lookup?path=/old-url

Looks up a single redirect by its old path. This is the storefront use case - your frontend calls this endpoint to check whether a URL has been moved before rendering a 404.

Query parameters

Parameter	Type	Required	Description
path	string	Yes	The old URL path to look up (1–2,048 chars)

Request

curl "https://api.hydrajs.dev/v1/redirects/lookup?path=/classic-t-shirt" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": {
		"id": "rdr_abc123def456ghij",
		"old_path": "/classic-t-shirt",
		"new_path": "/premium-t-shirt",
		"resource_type": "product",
		"resource_id": "prod_abc123",
		"created_at": "2026-06-15T10:30:00Z",
		"updated_at": "2026-06-15T10:30:00Z"
	}
}

Error 404 - redirect not found

{
	"error": {
		"code": "not_found",
		"message": "Redirect not found."
	}
}

---

Create a redirect

POST /v1/redirects

Creates a manual redirect from one path to another. If a redirect already exists for the same old_path, its target is updated instead of creating a duplicate.

Request body

Field	Type	Required	Description
old_path	string	Yes	The old URL path (1–2,048 chars)
new_path	string	Yes	The new URL path (1–2,048 chars)

Request

curl -X POST https://api.hydrajs.dev/v1/redirects \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "old_path": "/old-product-page",
    "new_path": "/new-product-page"
  }'

Response 201

{
	"data": {
		"id": "rdr_abc123def456ghij",
		"old_path": "/old-product-page",
		"new_path": "/new-product-page",
		"resource_type": null,
		"resource_id": null,
		"created_at": "2026-08-17T10:30:00Z",
		"updated_at": "2026-08-17T10:30:00Z"
	}
}

---

Delete a redirect

DELETE /v1/redirects/{id}

Permanently deletes a redirect. This is a hard delete - the redirect is removed immediately and cannot be recovered.

Request

curl -X DELETE https://api.hydrajs.dev/v1/redirects/rdr_abc123def456ghij \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

Error 404 - redirect not found

{
	"error": {
		"code": "not_found",
		"message": "Redirect not found."
	}
}

---

The redirect object

Field	Type	Description
id	string	Unique ID (prefix: rdr_)
old_path	string	The old URL path being redirected from
new_path	string	The new URL path being redirected to
resource_type	string | null	Associated resource type (product, collection) or null for manual redirects
resource_id	string | null	Associated resource ID or null for manual redirects
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp