Skip to main content
POST
Semantic search

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: write operations, authentication, payment verification, AI recommendations

Publishable Keys (Client-Safe):

  • Format: tybrite_pk_live_* (production) or tybrite_pk_test_* (sandbox)
  • Read-only access (GET requests only, plus POST semantic search)
  • ✅ Safe for client-side JavaScript, mobile apps, and public code
  • Allowed for: browsing products, search, CMS content, pricing queries

Endpoint-Specific Requirements:

  • Authentication endpoints (/v1/auth/*): Secret key required
  • 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)
  • All write operations: Secret key required
  • All read operations: Both key types allowed

Using a publishable key for restricted operations returns 403 Forbidden.

Headers

x-auth-token
string

Session token of a customer signed in through Galactic Core. Only used when personalize is true, to rank results toward that shopper's preferences. Optional everywhere else, and an absent or invalid credential simply returns unpersonalized results rather than an error.

x-external-auth
string

Signed identity assertion for a customer authenticated with your own identity provider. Serves the same purpose as x-auth-token; send whichever matches how the shopper signed in.

x-idp-token
string

A raw token from your own identity provider, which Galactic Core forwards to the store's configured Auth verifier. Serves the same purpose as x-auth-token.

Body

application/json
query
string
required

Natural language search query

limit
integer
default:20

Maximum number of results to return

Required range: 1 <= x <= 100
minScore
number<float>
default:0.3

Minimum similarity score threshold (0.0 to 1.0)

Required range: 0 <= x <= 1
personalize
boolean
default:false

When true and the request is made on behalf of a signed-in customer (identify the shopper with any of x-auth-token, x-external-auth, or x-idp-token), results are nudged toward the shopper's preferences while keeping query relevance primary (relevance is blended with preference, not replaced). Without a customer session, or for a shopper with no preference signal yet, ranking is by query relevance only.

Response

Success

query
string
results
object[]
totalResults
integer
message
string