Skip to main content
POST
Search by constraints

Authorizations

Authorization
string
header
required

API Key Authentication

Use your API key in the Authorization header:

Key Types:

Secret Keys (Server-Side Only):

  • Format: tybrite_sk_live_* (production) or tybrite_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) or tybrite_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-changing POST calls require a secret key, for store and marketplace keys alike; GET /v1/auth/me accepts 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 403 with the error code out_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 403 with endpoint_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

x-auth-token
string

The signed-in shopper, for a personalised ranking when they have granted personalisation. Customer session token from POST /v1/auth/login or POST /v1/auth/verify-otp. At most one of x-auth-token, x-external-auth, or x-idp-token.

x-external-auth
string

A bring-your-own-auth assertion identifying the shopper, for a personalised ranking. At most one of x-auth-token, x-external-auth, or x-idp-token.

x-idp-token
string

A raw token from the store's own identity provider for the shopper, for a personalised ranking. At most one of x-auth-token, x-external-auth, or x-idp-token.

Query Parameters

fields
string

Comma-separated top-level keys of data to return, e.g. fields=grand_total,lines.

Body

application/json
query
string

Free text. Matched by meaning where the store has semantic search, and against name, brand, category, SKU and tags.

Maximum string length: 300
price_min
number
Required range: x >= 0
price_max
number
Required range: x >= 0
category
string

A category or subcategory name (case-insensitive).

attributes
object

Attribute name to wanted value, e.g. {"color": "black"}.

in_stock_only
boolean
limit
integer
default:10
Required range: 1 <= x <= 50
offset
integer
default:0

Skip this many results of the ordered set. Send offset or cursor, not both.

Required range: 0 <= x <= 1000
cursor
string

The next_cursor of the previous page, sent with the same constraints. Send offset or cursor, not both.

Maximum string length: 200

Response

Matching products

data
object
required
evidence
object[]
required

Where each figure in data was read from.

computed_at
string<date-time>
required
environment
enum<string>
required
Available options:
production,
sandbox
currency
string | null

ISO 4217 code every amount in data is expressed in.