Search

10 endpoints. Each needs an API key or OAuth token with the scope shown; the key already names its store, so paths start at /v1/store. Generated from the live contract; also in openapi.json.

Synonyms, pinned results, redirects and the state of the search index

GET/v1/store/search/settings

Or name the store: GET /v1/stores/{storeId}/search/settings

storefront:readrole: storefront:readgetSearchSettings

Response SearchSettings

synonymsSearchSynonym[]required
rulesSearchRule[]required
defaultsobject[]required
- termsstring[]required
- oneWaybooleanrequired
indexRebuildSearchIndexResponserequired

Example

curl "https://api.shopfa.st/v1/store/search/settings" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY"

const res = await fetch('https://api.shopfa.st/v1/store/search/settings', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
  },
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.shopfa.st/v1/store/search/settings",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("GET", "https://api.shopfa.st/v1/store/search/settings", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

Add a synonym rule

POST/v1/store/search/synonyms

Or name the store: POST /v1/stores/{storeId}/search/synonyms

storefront:writerole: storefront:writecreateSearchSynonym

Body

termsstring[]required
oneWayboolean

Response SearchSynonym

idSearchSynonymIdrequired
termsstring[]required
oneWaybooleanrequired
createdAtTimestamprequired
updatedAtTimestamprequired

Example

curl -X POST "https://api.shopfa.st/v1/store/search/synonyms" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "terms": [
    "string"
  ],
  "oneWay": false
}'

const res = await fetch('https://api.shopfa.st/v1/store/search/synonyms', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "terms": [
      "string"
    ],
    "oneWay": false
  }),
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "POST",
    "https://api.shopfa.st/v1/store/search/synonyms",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "terms": [
        "string"
      ],
      "oneWay": False
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/search/synonyms", strings.NewReader(`{
  "terms": [
    "string"
  ],
  "oneWay": false
}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

Body

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

Change a synonym rule

PUT/v1/store/search/synonyms/{synonymId}

Or name the store: PUT /v1/stores/{storeId}/search/synonyms/{synonymId}

storefront:writerole: storefront:writeupdateSearchSynonym

Parameters

synonymIdssy_…pathrequired

Body

termsstring[]required
oneWayboolean

Response SearchSynonym

idSearchSynonymIdrequired
termsstring[]required
oneWaybooleanrequired
createdAtTimestamprequired
updatedAtTimestamprequired

Example

curl -X PUT "https://api.shopfa.st/v1/store/search/synonyms/ssy_0123456789abcdefghjk" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "terms": [
    "string"
  ],
  "oneWay": false
}'

const res = await fetch('https://api.shopfa.st/v1/store/search/synonyms/ssy_0123456789abcdefghjk', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "terms": [
      "string"
    ],
    "oneWay": false
  }),
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "PUT",
    "https://api.shopfa.st/v1/store/search/synonyms/ssy_0123456789abcdefghjk",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "terms": [
        "string"
      ],
      "oneWay": False
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("PUT", "https://api.shopfa.st/v1/store/search/synonyms/ssy_0123456789abcdefghjk", strings.NewReader(`{
  "terms": [
    "string"
  ],
  "oneWay": false
}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

synonymId

Body

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

Remove a synonym rule

DELETE/v1/store/search/synonyms/{synonymId}

Or name the store: DELETE /v1/stores/{storeId}/search/synonyms/{synonymId}

storefront:writerole: storefront:writedeleteSearchSynonym

Parameters

synonymIdssy_…pathrequired

Response Ok

okbooleanrequired

Example

curl -X DELETE "https://api.shopfa.st/v1/store/search/synonyms/ssy_0123456789abcdefghjk" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY"

const res = await fetch('https://api.shopfa.st/v1/store/search/synonyms/ssy_0123456789abcdefghjk', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
  },
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "DELETE",
    "https://api.shopfa.st/v1/store/search/synonyms/ssy_0123456789abcdefghjk",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("DELETE", "https://api.shopfa.st/v1/store/search/synonyms/ssy_0123456789abcdefghjk", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

synonymId

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

Pin products to a search, or send a search to a page

POST/v1/store/search/rules

Or name the store: POST /v1/stores/{storeId}/search/rules

storefront:writerole: storefront:writecreateSearchRule

Body

kind"pin" | "redirect"required
querystringrequired
productIdsprd_…[]
urlstring | null
enabledboolean

Response SearchRule

idSearchRuleIdrequired
kindSearchRuleKindrequired
querystringrequired
normalizedstringrequired
productIdsProductId[]required
urlstringrequired
enabledbooleanrequired
createdAtTimestamprequired
updatedAtTimestamprequired

Example

curl -X POST "https://api.shopfa.st/v1/store/search/rules" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "pin",
  "query": "string",
  "productIds": [],
  "url": null,
  "enabled": true
}'

const res = await fetch('https://api.shopfa.st/v1/store/search/rules', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "kind": "pin",
    "query": "string",
    "productIds": [],
    "url": null,
    "enabled": true
  }),
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "POST",
    "https://api.shopfa.st/v1/store/search/rules",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "kind": "pin",
      "query": "string",
      "productIds": [],
      "url": None,
      "enabled": True
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/search/rules", strings.NewReader(`{
  "kind": "pin",
  "query": "string",
  "productIds": [],
  "url": null,
  "enabled": true
}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

Body

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

Change a pin or redirect

PUT/v1/store/search/rules/{ruleId}

Or name the store: PUT /v1/stores/{storeId}/search/rules/{ruleId}

storefront:writerole: storefront:writeupdateSearchRule

Parameters

ruleIdsrl_…pathrequired

Body

kind"pin" | "redirect"required
querystringrequired
productIdsprd_…[]
urlstring | null
enabledboolean

Response SearchRule

idSearchRuleIdrequired
kindSearchRuleKindrequired
querystringrequired
normalizedstringrequired
productIdsProductId[]required
urlstringrequired
enabledbooleanrequired
createdAtTimestamprequired
updatedAtTimestamprequired

Example

curl -X PUT "https://api.shopfa.st/v1/store/search/rules/srl_0123456789abcdefghjk" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "pin",
  "query": "string",
  "productIds": [],
  "url": null,
  "enabled": true
}'

const res = await fetch('https://api.shopfa.st/v1/store/search/rules/srl_0123456789abcdefghjk', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "kind": "pin",
    "query": "string",
    "productIds": [],
    "url": null,
    "enabled": true
  }),
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "PUT",
    "https://api.shopfa.st/v1/store/search/rules/srl_0123456789abcdefghjk",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
    json={
      "kind": "pin",
      "query": "string",
      "productIds": [],
      "url": None,
      "enabled": True
    },
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("PUT", "https://api.shopfa.st/v1/store/search/rules/srl_0123456789abcdefghjk", strings.NewReader(`{
  "kind": "pin",
  "query": "string",
  "productIds": [],
  "url": null,
  "enabled": true
}`))
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

ruleId

Body

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

Remove a pin or redirect

DELETE/v1/store/search/rules/{ruleId}

Or name the store: DELETE /v1/stores/{storeId}/search/rules/{ruleId}

storefront:writerole: storefront:writedeleteSearchRule

Parameters

ruleIdsrl_…pathrequired

Response Ok

okbooleanrequired

Example

curl -X DELETE "https://api.shopfa.st/v1/store/search/rules/srl_0123456789abcdefghjk" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY"

const res = await fetch('https://api.shopfa.st/v1/store/search/rules/srl_0123456789abcdefghjk', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
  },
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "DELETE",
    "https://api.shopfa.st/v1/store/search/rules/srl_0123456789abcdefghjk",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("DELETE", "https://api.shopfa.st/v1/store/search/rules/srl_0123456789abcdefghjk", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

ruleId

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

Rebuild the search index now (it also refreshes itself after catalog changes)

POST/v1/store/search/reindex

Or name the store: POST /v1/stores/{storeId}/search/reindex

storefront:writerole: storefront:writerebuildSearchIndex

Response RebuildSearchIndexResponse

productsintegerrequired
collectionsintegerrequired
pagesintegerrequired
termsintegerrequired
builtAtTimestamp | nullrequired
buildMsinteger | nullrequired

Example

curl -X POST "https://api.shopfa.st/v1/store/search/reindex" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY"

const res = await fetch('https://api.shopfa.st/v1/store/search/reindex', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
  },
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "POST",
    "https://api.shopfa.st/v1/store/search/reindex",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("POST", "https://api.shopfa.st/v1/store/search/reindex", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

What buyers get for a search (synonyms, typos, pins and redirects applied), not counted in analytics

GET/v1/store/search/preview

Or name the store: GET /v1/stores/{storeId}/search/preview

storefront:readrole: storefront:readpreviewSearch

Parameters

qstringquery

Response StorefrontSuggest

querySearchQueryInforequired
productsSearchProductHit[]required
collectionsSearchLinkHit[]required
pagesSearchLinkHit[]required
categoriesSearchLinkHit[]required
totalintegerrequired
popularstring[]required

Example

curl "https://api.shopfa.st/v1/store/search/preview" \
  -H "Authorization: Bearer $SHOPFAST_API_KEY"

const res = await fetch('https://api.shopfa.st/v1/store/search/preview', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SHOPFAST_API_KEY}`,
  },
});
if (!res.ok) throw new Error((await res.json()).detail);
const data = await res.json();

import os, requests

res = requests.request(
    "GET",
    "https://api.shopfa.st/v1/store/search/preview",
    headers={"Authorization": f"Bearer {os.environ['SHOPFAST_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

req, _ := http.NewRequest("GET", "https://api.shopfa.st/v1/store/search/preview", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("SHOPFAST_API_KEY"))
res, err := http.DefaultClient.Do(req)

Try it with your key

API base URLAPI key or token

Use a test key on a development store. The key stays in this tab (sessionStorage) and is sent only to the base URL above.

Search

Synonyms, pinned results, redirects and the state of the search index

Response SearchSettings

Example

Add a synonym rule

Body

Response SearchSynonym

Example

Change a synonym rule

Parameters

Body

Response SearchSynonym

Example

Remove a synonym rule

Parameters

Response Ok

Example

Pin products to a search, or send a search to a page

Body

Response SearchRule

Example

Change a pin or redirect

Parameters

Body

Response SearchRule

Example

Remove a pin or redirect

Parameters

Response Ok

Example

Rebuild the search index now (it also refreshes itself after catalog changes)

Response RebuildSearchIndexResponse

Example

What buyers get for a search (synonyms, typos, pins and redirects applied), not counted in analytics

Parameters

Response StorefrontSuggest

Example

Top searches, searches with no results, click-through and searches that led to a purchase

Parameters

Response SearchAnalytics

Example