Skip to main content

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.

MethodPathDescription
GET/redirectsList 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​

FieldTypeDescription
urlstringWhere the shopper is sent. An absolute http:// or https:// URL, up to 2,048 characters.
matchTypestringEXACT or CONTAINS. See Match types.
termstringRead-only. The term as last written.
revisionstringRead-only. See Revisions.
updatedAtstringRead-only. When the redirect was last saved.
updatedBystring or nullRead-only. The console user's email, api_key:<id> for an API key, or null when unknown.

Match types​

matchTypeFires whenExample term → query that fires
EXACTThe whole query equals the term.gift cards → Gift Cards
CONTAINSThe 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, is 400 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 -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"
}'

Returns the stored redirect.

  • A PUT to another spelling of an existing term updates that redirect. The stored term's lower-case form (gift%20cards over Gift Cards) keeps the stored term, and its revision when url and matchType are unchanged. Any other spelling replaces the stored term, including other capitals (Gift%20Card over gift card) and other punctuation (gift%20card over gift-card).
  • Creating a 501st redirect fails with 422 limit_max_redirects_per_index.
  • A stale If-Match, or If-None-Match: * on an existing redirect, is 412 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.