REST API

The Search Ultimate extension for Magento 2 exposes a REST API for the search configuration entities that Magento itself does not publish: synonyms, stopwords, and search terms together with their redirect URLs.

This is useful when you want to:

Let an AI agent or an MCP client manage search configuration without Magento admin access.
Import synonyms, stopwords, or search-term redirects from an external PIM, CMS, or spreadsheet.
Keep search configuration in sync across several Magento installations.
Audit redirects whose targets were deleted or moved — see Search terms.

Base URL

All endpoints follow Magento's standard REST API pattern:

https://<your-store-domain>/rest/<store-code>/V1/mst-search/

The store code is accepted but ignored by these endpoints — see Store scope — so the shorter form is the one to use:

https://<your-store-domain>/rest/V1/mst-search/

Store scope

The store code in the URL does not scope these endpoints. Scope is carried by the store_id field of the entity itself, so /rest/de/V1/mst-search/search-terms and /rest/V1/mst-search/search-terms behave identically — a payload without store_id is stored against store 0 in both cases, not against the store view named in the path.

Send the store view's numeric ID in the body instead. 0 means every store view for synonyms and stopwords, but for search terms it means a scope no storefront searches — see the warning on that page.

Authentication

All endpoints require an admin Bearer token. Obtain one by calling:

POST /rest/V1/integration/admin/token

Request body:

{
  "username": "admin",
  "password": "your-admin-password"
}

Response:

"abc123xyz..."

Include the token in every subsequent request:

Authorization: Bearer abc123xyz...

Permissions

Each resource is guarded by the same ACL resource as the admin screen it mirrors, so an integration token only reaches what its role already allows. Grant these at System -> Permissions -> User Roles -> [role] -> Role Resources.

Resource	ACL resource	Role resource	Admin screen
Synonyms	`Magento_Search::synonyms`	Search Synonyms	System -> Search Management -> Manage Synonyms
Stopwords	`Mirasvit_Search::search_stopword`	Stopwords	System -> Search Management -> Manage Stopwords
Search terms	`Magento_Search::search`	Search Terms	Marketing -> SEO & Search -> Search Terms

Filtering and pagination

All list endpoints accept Magento's standard searchCriteria query parameters.

warning

searchCriteria is required on every list request. A request without it is refused with 400 and the message "searchCriteria" is required. Enter and try again. To list everything, pass the bare parameter: ?searchCriteria.

Example — stopwords for store view 1, 10 per page:

GET /rest/V1/mst-search/stopwords
  ?searchCriteria[filter_groups][0][filters][0][field]=store_id
  &searchCriteria[filter_groups][0][filters][0][value]=1
  &searchCriteria[filter_groups][0][filters][0][condition_type]=eq
  &searchCriteria[pageSize]=10
  &searchCriteria[currentPage]=1

List response envelope:

{
  "items": [ ... ],
  "search_criteria": { ... },
  "total_count": 42
}

The write contract

No write flushes the cache or triggers a reindex. This is deliberate: an import of several hundred synonyms would otherwise invalidate the cache several hundred times. Your integration decides when to pay that cost, using the standard Magento tools:

php -f bin/magento cache:clean
php -f bin/magento indexer:reindex catalogsearch_fulltext

What that means in practice:

Synonym writes affect search results immediately. A synonym group saved over REST expands the next storefront query with no cache flush and no reindex.
Search-term redirects take effect immediately. A term whose redirect was set over REST redirects the next shopper who searches it, with no cache flush and no reindex.
Stopwords are honoured at query time, so a write needs no reindex: the stopword list is read from the database on each search request rather than baked into the index.
Pages already rendered into the full-page cache do not change. Search results and autocomplete are generated per query, so this only matters for cached storefront pages that embed search output.

Fast Mode and synonyms

When Fast Mode is enabled for autocomplete, the autocomplete suggestions are served from a cached data file that is regenerated only by a full catalogsearch_fulltext reindex. A synonym write — over REST or through the admin — does not regenerate it, so autocomplete keeps using the previous synonym list until you run:

php -f bin/magento indexer:reindex catalogsearch_fulltext

Ordinary search results are unaffected and update immediately. This is a known limitation and will be removed from this page once it is fixed.

Troubleshooting

Decoding error: Unable to unserialize value. Error: Syntax error

The request carried a body that is not valid JSON, and Magento tries to decode the body of every request — including GET and DELETE, which should not have one at all. A single stray space or blank line is enough to trigger it, and the message says nothing about which part of the request is at fault.

Send GET and DELETE with no body. In Postman that means setting the Body tab to none, and removing any Content-Type: application/json header that was added by hand and outlived the body it belonged to.

Query parameters with square brackets

searchCriteria[filter_groups][0]... works both literally and percent-encoded. Send one or the other consistently rather than mixing the two in a single URL.

Endpoints

Synonyms — CRUD operations for synonym groups
Stopwords — CRUD operations for stopwords
Search terms — CRUD operations for search terms and their redirect URLs

Base URL​

Store scope​

Authentication​

Permissions​

Filtering and pagination​

The write contract​

Troubleshooting​

Endpoints​