Read a shopper's message
A shopper’s message in, what kind of message it is (intent) out, and for a product request the exact constraint
object POST /v1/agent/search accepts, plus unresolved — the parts of the request it could not map to a
constraint.
It works without the hosted helpers. A greeting, a thank-you, a goodbye, a question about an order and a plain
question about the store (delivery with an optional place, returns, opening hours, payment, contact) are read by
fixed rules and cost nothing, whether or not the store has hosted helpers on; a message that asks several of those
is answered for each. Every other message is read by the hosted helper when the store has it on, and by the same
rules over the store’s own vocabulary when it does not: a price limit (“under 50”, “between 20 and 40”), in stock,
a colour that is one of the store’s own colour values, and a category named as the store names it become
constraints; any other words stay in query; a word the rules cannot turn into a filter is listed in unresolved.
classified_by says which read the message. The call never answers 403 helpers_unavailable.
intent | The message | constraints | reply |
|---|---|---|---|
shop | Asks for products, or changes an earlier product request | The search to run | Absent |
question | Asks about the store: delivery, returns, opening hours, contact, payment | Empty | The store’s published answer |
small_talk | A greeting, a thank-you or a goodbye | Empty | A short answer |
order_help | Asks about an existing order | Empty | How to check an order, with the store’s contact |
unclear | Cannot be read as any of these | Empty | A request for more detail |
Only a shop message carries constraints, so a greeting is never searched for. A reply is composed from what the
store has published: its shipping zones and distance tiers, its returns setting and window, its payment methods,
its profile (contact, support hours) and the opening of its published shipping or returns policy. A fact the store
has not published is never stated; the reply says the store has not published it and gives the contact the store
did publish. A greeting, a thank-you or a goodbye on its own is recognised without a model and debits nothing
(usage.credits_debited: 0).
suggestions holds two or three follow-up prompts drawn from the store’s live collections and the categories its
online products are in. Each text can be sent back to interpret as it is.
A message read by the hosted helper debits the store’s AI credits at the true cost of the call; usage reports what
was debited (credits_debited: 0 for a message read by rules). A failed helper call keeps no credits and the
message is read by the rules instead. The call is limited per shopper at the store as described under the agent
fair-use budgets, in addition to the standard limits.
A publishable key spends the store’s credits too, when the helper reads the message. A publishable key is public, so anyone holding it can make these calls, and each one the helper reads debits the merchant’s balance (and can trigger the merchant’s automatic top-up). The merchant sets a daily limit on that spend, counted over the last 24 hours; once it is reached, or when the helpers are off, paused or out of credits, the message is read by the rules and nothing is debited.
With a marketplace operator key a message read by the helper is paid from the marketplace operator’s own AI credits, never a seller’s; when the operator has not switched hosted helpers on or its credits are exhausted, the rules read the message.
A follow-up in a saved conversation. With conversation_id, the request is read in the context of that
storefront conversation (/v1/agent/me/conversations): its last six turns, the prices of the results the storefront
last showed, and the constraints the previous interpret on it returned. “cheaper ones” or “in blue” then refine
the earlier request. The call names the conversation’s owner the way the conversation endpoints do (a shopper
credential, or x-session-id for a guest), and is refused with the same codes when the store’s assistant settings
do not allow it (403 shopping_assistant_disabled, history_disabled, guests_not_allowed) or when the
conversation is not the caller’s (404 not_found). The constraints returned are kept on the conversation for the
next follow-up; no turn is added. Only a shop message updates them, so “cheaper ones” after “thanks” still refines
the last product request. A follow-up keeps the earlier request and applies the change: a new value replaces the old
one, a new attribute is added, “cheaper” sets price_max just below the lowest price last shown, and “more expensive”
sets price_min just above the highest.
curl --request POST \
--url https://api.tybritelabs.com/v1/agent/interpret \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "a black hoodie under 60 for my brother"
}
'import requests
url = "https://api.tybritelabs.com/v1/agent/interpret"
payload = { "query": "a black hoodie under 60 for my brother" }
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: 'a black hoodie under 60 for my brother'})
};
fetch('https://api.tybritelabs.com/v1/agent/interpret', 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/interpret",
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' => 'a black hoodie under 60 for my brother'
]),
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/interpret"
payload := strings.NewReader("{\n \"query\": \"a black hoodie under 60 for my brother\"\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/interpret")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"a black hoodie under 60 for my brother\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/agent/interpret")
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\": \"a black hoodie under 60 for my brother\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"intent": "shop",
"suggestions": [
{
"text": "Show me Out and About",
"kind": "collection",
"collection_id": "323d9dbc-1c9d-42a2-a069-ae4031750e3b"
},
{
"text": "Browse Men's Clothing",
"kind": "category",
"category": "Men's Clothing"
}
],
"constraints": {
"query": "hoodie",
"price_max": 60,
"attributes": {
"color": "black"
},
"in_stock_only": true
},
"unresolved": [
"for my brother"
]
},
"evidence": [
{
"source": "hosted_helper",
"operation": "interpret",
"field": "constraints, intent"
}
],
"computed_at": "2026-09-28T21:49:12.108Z",
"currency": null,
"environment": "sandbox",
"usage": {
"credits_debited": 0.000412,
"model_class": "fast"
}
}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
Body
Response
The constraints
curl --request POST \
--url https://api.tybritelabs.com/v1/agent/interpret \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "a black hoodie under 60 for my brother"
}
'import requests
url = "https://api.tybritelabs.com/v1/agent/interpret"
payload = { "query": "a black hoodie under 60 for my brother" }
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: 'a black hoodie under 60 for my brother'})
};
fetch('https://api.tybritelabs.com/v1/agent/interpret', 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/interpret",
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' => 'a black hoodie under 60 for my brother'
]),
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/interpret"
payload := strings.NewReader("{\n \"query\": \"a black hoodie under 60 for my brother\"\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/interpret")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"a black hoodie under 60 for my brother\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tybritelabs.com/v1/agent/interpret")
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\": \"a black hoodie under 60 for my brother\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"intent": "shop",
"suggestions": [
{
"text": "Show me Out and About",
"kind": "collection",
"collection_id": "323d9dbc-1c9d-42a2-a069-ae4031750e3b"
},
{
"text": "Browse Men's Clothing",
"kind": "category",
"category": "Men's Clothing"
}
],
"constraints": {
"query": "hoodie",
"price_max": 60,
"attributes": {
"color": "black"
},
"in_stock_only": true
},
"unresolved": [
"for my brother"
]
},
"evidence": [
{
"source": "hosted_helper",
"operation": "interpret",
"field": "constraints, intent"
}
],
"computed_at": "2026-09-28T21:49:12.108Z",
"currency": null,
"environment": "sandbox",
"usage": {
"credits_debited": 0.000412,
"model_class": "fast"
}
}
