Redirects API
Overview
A redirect sends a shopper who searches for a term straight to a URL, such as a gift card page for
gift cards or a size guide for size chart, instead of showing search results.
| Method | Path | Description |
|---|---|---|
GET | /redirects | List redirects |
GET | /redirects/{term} | Get a redirect |
PUT | /redirects/{term} | Create or replace a redirect |
DELETE | /redirects/{term} | Delete a redirect |
Paths are relative to https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise.
Encode {term} as one path segment (see Triggers in the path).
Redirect fields
| Field | Type | Description |
|---|---|---|
url | string | Where the shopper is sent. An absolute http:// or https:// URL, up to 2,048 characters. |
matchType | string | EXACT or CONTAINS. See Match types. |
term | string | Read-only. The term as last written. |
revision | string | Read-only. See Revisions. |
updatedAt | string | Read-only. When the redirect was last saved. |
updatedBy | string or null | Read-only. The console user's email, api_key:<id> for an API key, or null when unknown. |
Match types
matchType | Fires when | Example term → query that fires |
|---|---|---|
EXACT | The whole query equals the term. | gift cards → Gift Cards |
CONTAINS | The term is one of the query's words. The term must be a single word of letters and digits. | giftcard → buy a giftcard |
For CONTAINS, the query is split on whitespace, and each word is lower-cased with everything but
letters and digits removed before it is compared. So tshirt fires for t-shirt, but gift does
not fire for gift-card.
When several redirects match, one whose term is the whole query wins; among CONTAINS matches, the
word that comes first in the query wins.
Terms
Terms are matched in a normalised form: Unicode NFC, edge whitespace removed, lower-cased, and
every character other than a letter, digit or _ replaced with _. So Gift Card, gift-card
and gift_card all address the same redirect.
- A term must contain at least one letter or digit. A blank term, or one of only punctuation
(
!,*,-) or invisible characters, is400 validation_error. - A term is at most 200 characters, and may end in
/.
URLs
url must be an absolute http:// or https:// URL with a lower-case scheme and no whitespace.
Relative paths (/collections/sale), other schemes (javascript:, data:) and protocol-relative
URLs (//shop.example.com) are 400 validation_error. The storefront moves a URL on the shop's
own domain onto the host the shopper is browsing.
Redirects created in the console before URL validation may hold other values; they are returned as
stored and can be replaced, but not written back unchanged unless they are an http(s) URL with
only an upper-case scheme or spaces.
List redirects
Endpoint: GET /redirects
Returns every redirect on the index, ordered by normalised term. There are at most 500, so the list isn't paginated.
curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/redirects \
-H "Authorization: Bearer {api_key}"
{
"items": [
{
"term": "gift cards",
"url": "https://shop.example.com/collections/gift-cards",
"matchType": "EXACT",
"revision": "0a8d3f61b2c94e7d8f5a6b1c3d2e4f70",
"updatedAt": "2026-11-02T08:41:10.512Z",
"updatedBy": "merchandiser@example.com"
}
]
}
Get a redirect
Endpoint: GET /redirects/{term}
curl https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/redirects/gift%20cards \
-H "Authorization: Bearer {api_key}"
Returns the redirect, or 404 redirect_not_found.
Create or replace a redirect
Endpoint: PUT /redirects/{term}
Both url and matchType are required. Send If-Match to update only the revision you read, or
If-None-Match: * to create only if no redirect has the term.
- cURL
- JavaScript
curl -X PUT https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/redirects/gift%20cards \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"url": "https://shop.example.com/collections/gift-cards",
"matchType": "EXACT"
}'
const term = encodeURIComponent("gift cards");
await fetch(`https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/redirects/${term}`, {
method: "PUT",
headers: {
Authorization: "Bearer {api_key}",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://shop.example.com/collections/gift-cards",
matchType: "EXACT",
}),
});
Returns the stored redirect.
- A
PUTto another spelling of an existing term updates that redirect. The stored term's lower-case form (gift%20cardsoverGift Cards) keeps the stored term, and its revision whenurlandmatchTypeare unchanged. Any other spelling replaces the stored term, including other capitals (Gift%20Cardovergift card) and other punctuation (gift%20cardovergift-card). - Creating a 501st redirect fails with
422 limit_max_redirects_per_index. - A stale
If-Match, orIf-None-Match: *on an existing redirect, is412 revision_mismatch.
Delete a redirect
Endpoint: DELETE /redirects/{term}
curl -X DELETE https://ecom.marqo-ep.ai/api/v1/indexes/{index_name}/merchandise/redirects/gift%20cards \
-H "Authorization: Bearer {api_key}"
Returns 204, or 404 redirect_not_found if no redirect has the term, including on a retry after
a delete that succeeded. Takes an optional If-Match.
When redirects go live
Redirects don't wait for the five-minute rule export. Search reads them directly, and edges cache an index's redirects for up to 10 minutes, so a saved redirect is normally live within 10 minutes.