Search by constraints
Constraint search over the store’s catalogue, ranked by the store’s own search. With a query, the order is the
order the store’s search gives that query (POST /v1/search where the store’s plan includes semantic search,
otherwise GET /v1/search), with the merchant’s search rules applied: a product pinned for the query is shown
first in the merchant’s order, a boosted one is lifted and a buried one is shown last. The constraints only remove
results, so what remains keeps the store’s order (ranking: store_search). Products the store’s search did not
return are added after its results and before any it buried: a direct match on brand, category, SKU or tags, and
the products of a collection the query names (collections), so “summer” finds the store’s Summer collection.
Without a query the store’s search has no order to give: the store’s most-added-to-cart products come first,
then products on sale or in an offer, then the rest by name (ranking: catalogue).
The store’s search also applies the merchant’s synonyms, its ranking by popularity, promotions and stock when the
store has turned it on, and its reading of a sentence that matches no product name (searchProducts): “best
products for summer” is read as “summer”, so the storefront’s search and this search return the same products. The
direct match here reads the query the same way, setting aside words that carry no product meaning.
Redirects. When the merchant sends the query somewhere (a page address, a collection, a category or a
product), redirect names it, with the same shape as the store search’s redirect. It is a suggestion to offer
the shopper beside the results; nothing navigates on its own. Null when there is none.
Paging. limit results are returned from offset (default 0) of one ordered set: the store’s search order,
then what this search adds, then what a rule buried. next_cursor (or next_offset) continues it; a cursor is
valid only for the constraints and personalisation it was issued for, and a mismatched one is refused with 400.
total_matched is the size of the whole set; has_more is false on its last page. The order is recomputed the same
way for every page, so a page repeats nothing and skips nothing unless the catalogue changes between requests.
Paging is for store keys; a marketplace search returns one page.
Every result carries match_reasons (why it is in the results, in words a shopper can read) and badges (short
labels for display). A result never carries a score. A product a rule pins or boosts carries the featured badge,
labelled “Featured”; which products a rule buries is not disclosed.
Badge code | Shown when | label |
|---|---|---|
featured | The merchant’s search rule pins or boosts the product for this query | Featured |
collection | The product is in a collection the query names | The collection’s name |
on_sale | The product’s online sale price is below its online price | On sale |
offer | The product is part of a live buy-one-get-one or bundle offer | Buy one, get one / Bundle deal |
bestseller | The product is among the store’s most-added-to-cart products over the last 7 days (a measured list only) | Popular |
in_your_size | A size was asked for in attributes and the product has it | In your size |
in_stock_low | The product is in stock at or below the store’s low-stock threshold | Only N left |
With a shopper credential (x-auth-token, x-external-auth or x-idp-token) for a shopper who has granted
personalisation (POST /v1/agent/me/consent), the store’s search ranks toward that shopper’s taste, as it does on
the storefront (personalised: true). A credential that does not verify is refused with 401.
attributes are matched against each product’s variant attributes, product attributes, brand and category — use
POST /v1/agent/fit to check a product’s published specifications.
price is the shopper price of the product’s default variant: its online sale price when one
applies, otherwise its online price. list_price is that variant’s online price. The amount a shopper
is charged, after dynamic pricing, promotions, shipping and tax, comes from POST /v1/agent/quote.
in_stock_only checks the variants of up to 20 multi-variant products per request; a product beyond that
is excluded unless its default variant is in stock.
With a marketplace operator key the search spans every active seller of that marketplace and no other.
Each result names its seller (merchant_store_id, merchant_name), price is in the marketplace’s
currency, sellers_matched counts the sellers among the results, and matching is on name, brand,
category, SKU and tags (semantic_search: not_requested).
curl --request POST \
--url https://api.tybritelabs.com/v1/agent/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "hoodie",
"price_max": 60,
"in_stock_only": true,
"limit": 2
}
'import requests
url = "https://api.tybritelabs.com/v1/agent/search"
payload = {
"query": "hoodie",
"price_max": 60,
"in_stock_only": True,
"limit": 2
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({query: 'hoodie', price_max: 60, in_stock_only: true, limit: 2})
};
fetch('https://api.tybritelabs.com/v1/agent/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tybritelabs.com/v1/agent/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'hoodie',
'price_max' => 60,
'in_stock_only' => true,
'limit' => 2
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tybritelabs.com/v1/agent/search"
payload := strings.NewReader("{\n \"query\": \"hoodie\",\n \"price_max\": 60,\n \"in_stock_only\": true,\n \"limit\": 2\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/agent/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"hoodie\",\n \"price_max\": 60,\n \"in_stock_only\": true,\n \"limit\": 2\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/agent/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"hoodie\",\n \"price_max\": 60,\n \"in_stock_only\": true,\n \"limit\": 2\n}"
response = http.request(request)
puts response.read_body{
"data": {
"results": [
{
"product_id": "289533e8-f5b6-4d4f-bb23-2127875feb70",
"variant_id": "fbe89cdf-90a3-4050-a43b-e4c42302484a",
"name": "Galactic Zip Hoodie",
"brand": "Galactic",
"category": "Wearables",
"subcategory": "Hoodies",
"price": 48,
"list_price": 48,
"currency": "EUR",
"in_stock": true,
"stock": 25,
"has_variants": true,
"thumbnail_url": "https://images.unsplash.com/photo-1565693413579-8a73ffa8de15?w=400",
"attributes": {
"brand": "Galactic",
"category": "Wearables",
"subcategory": "Hoodies"
},
"match_reasons": [
{
"constraint": "query",
"detail": "Close to what you searched for, \"hoodie\""
},
{
"constraint": "price",
"detail": "Within your price range (48)"
},
{
"constraint": "in_stock_only",
"detail": "In stock"
},
{
"constraint": "featured",
"detail": "Featured by the store"
}
],
"badges": [
{
"code": "featured",
"label": "Featured"
},
{
"code": "bestseller",
"label": "Popular"
}
]
}
],
"total_matched": 1,
"scanned": 216,
"catalog_truncated": false,
"semantic_search": "used",
"ranking": "store_search",
"personalised": false,
"collections": [],
"constraints": {
"query": "hoodie",
"price_max": 60,
"in_stock_only": true
}
},
"evidence": [
{
"source": "products",
"operation": "GET /v1/products",
"field": "price"
},
{
"source": "products",
"operation": "GET /v1/products",
"field": "stock"
},
{
"source": "search",
"operation": "POST /v1/search",
"field": "results (order)"
},
{
"source": "products",
"operation": "GET /v1/products/{id}",
"field": "variants.stock"
},
{
"source": "recommendations",
"operation": "GET /v1/discovery/most-added-to-cart",
"field": "products"
}
],
"computed_at": "2026-09-28T21:53:25.353Z",
"currency": "EUR",
"environment": "sandbox"
}Authorizations
API Key Authentication
Use your API key in the Authorization header:
Authorization: Bearer tybrite_sk_live_YOUR_KEY
Key Types:
Secret Keys (Server-Side Only):
- Format:
tybrite_sk_live_*(production) ortybrite_sk_test_*(sandbox) - Full read/write access to all endpoints
- ⚠️ NEVER expose in client-side code or public repositories
- Required for: every write a shopper does not make for themselves, authentication, payment verification, AI recommendations
Publishable Keys (Client-Safe):
- Format:
tybrite_pk_live_*(production) ortybrite_pk_test_*(sandbox) - Catalogue reads, plus the actions a shopper takes for themselves
- ✅ Safe for client-side JavaScript, mobile apps, and public code
- Allowed for: browsing products, search, CMS content, pricing queries, cart and wishlist, reviews, storefront events, and the Agent API's quotes, cart drafts and checkout intents
Endpoint-Specific Requirements:
- Authentication endpoints (
/v1/auth/*): state-changingPOSTcalls require a secret key, for store and marketplace keys alike;GET /v1/auth/meaccepts either key - Payment verification (
POST /v1/payments/verify): Secret key required - AI Recommendations (
POST /v1/recommendations): Secret key required - Semantic Search (
POST /v1/search): Both key types allowed (read-only operation) - Shopper actions (cart, wishlist, reviews, storefront events, Agent API quotes, cart drafts and checkout intents): Both key types allowed
- All other write operations: Secret key required
- All read operations: Both key types allowed
Using a publishable key for restricted operations returns 403 Forbidden.
Limited publishable keys:
A publishable key can be limited to the products that carry one tag (for example starter:jewellery), created from
the store's Developers page. The limit applies to the key, never to the shopper: shopper sign-up and sign-in stay store-wide.
- Reads return only the slice: products (with their facets, filters, search, brands and specifications), categories and
subcategories that hold in-slice products, collections, promotions, posts and lookbooks that carry the tag, reviews of
in-slice products, prices, discovery lists and the store information summary, with every count computed on the slice.
A product outside the slice answers
404, as if it did not exist. - A write that names a product or variant outside the slice (adding to the cart or wishlist, reserving stock, an order line,
a review, a promotion calculation, a storefront event) answers
403with the error codeout_of_scope, and nothing is written or reserved. An order is refused as a whole. - A route that carries no slice behaviour is not available to the key: it answers
403withendpoint_not_allowed. - Orders placed through such a key record the tag on the order's attribution as
key_scope. - Secret keys and connected-app keys cannot be limited.
- Responses are cached per key limit: a limited key never receives a response cached for the whole store, and the reverse.
Headers
Query Parameters
Body
Response
Matching products
curl --request POST \
--url https://api.tybritelabs.com/v1/agent/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "hoodie",
"price_max": 60,
"in_stock_only": true,
"limit": 2
}
'import requests
url = "https://api.tybritelabs.com/v1/agent/search"
payload = {
"query": "hoodie",
"price_max": 60,
"in_stock_only": True,
"limit": 2
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({query: 'hoodie', price_max: 60, in_stock_only: true, limit: 2})
};
fetch('https://api.tybritelabs.com/v1/agent/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tybritelabs.com/v1/agent/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'hoodie',
'price_max' => 60,
'in_stock_only' => true,
'limit' => 2
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tybritelabs.com/v1/agent/search"
payload := strings.NewReader("{\n \"query\": \"hoodie\",\n \"price_max\": 60,\n \"in_stock_only\": true,\n \"limit\": 2\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tybritelabs.com/v1/agent/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"hoodie\",\n \"price_max\": 60,\n \"in_stock_only\": true,\n \"limit\": 2\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/agent/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"hoodie\",\n \"price_max\": 60,\n \"in_stock_only\": true,\n \"limit\": 2\n}"
response = http.request(request)
puts response.read_body{
"data": {
"results": [
{
"product_id": "289533e8-f5b6-4d4f-bb23-2127875feb70",
"variant_id": "fbe89cdf-90a3-4050-a43b-e4c42302484a",
"name": "Galactic Zip Hoodie",
"brand": "Galactic",
"category": "Wearables",
"subcategory": "Hoodies",
"price": 48,
"list_price": 48,
"currency": "EUR",
"in_stock": true,
"stock": 25,
"has_variants": true,
"thumbnail_url": "https://images.unsplash.com/photo-1565693413579-8a73ffa8de15?w=400",
"attributes": {
"brand": "Galactic",
"category": "Wearables",
"subcategory": "Hoodies"
},
"match_reasons": [
{
"constraint": "query",
"detail": "Close to what you searched for, \"hoodie\""
},
{
"constraint": "price",
"detail": "Within your price range (48)"
},
{
"constraint": "in_stock_only",
"detail": "In stock"
},
{
"constraint": "featured",
"detail": "Featured by the store"
}
],
"badges": [
{
"code": "featured",
"label": "Featured"
},
{
"code": "bestseller",
"label": "Popular"
}
]
}
],
"total_matched": 1,
"scanned": 216,
"catalog_truncated": false,
"semantic_search": "used",
"ranking": "store_search",
"personalised": false,
"collections": [],
"constraints": {
"query": "hoodie",
"price_max": 60,
"in_stock_only": true
}
},
"evidence": [
{
"source": "products",
"operation": "GET /v1/products",
"field": "price"
},
{
"source": "products",
"operation": "GET /v1/products",
"field": "stock"
},
{
"source": "search",
"operation": "POST /v1/search",
"field": "results (order)"
},
{
"source": "products",
"operation": "GET /v1/products/{id}",
"field": "variants.stock"
},
{
"source": "recommendations",
"operation": "GET /v1/discovery/most-added-to-cart",
"field": "products"
}
],
"computed_at": "2026-09-28T21:53:25.353Z",
"currency": "EUR",
"environment": "sandbox"
}
