Tenants
Stores, settings, flags, onboarding.
6 endpoints.
GET
/v1/tenantsStores I belong to
Needs a key or a dashboard session
Responses
- 200Successful Response
TenantOut[]
POST
/v1/tenantsTenants Create
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | null | no | Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$ |
Request body application/json TenantCreate
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | max length 200 |
slug | string | null | no | pattern ^[a-z0-9][a-z0-9-]{2,62}$ |
default_locale | string | no | default "en" · pattern ^[a-z]{2}$ |
locales | string[] | no | Catalog languages. |
currency | string | no | default "USD" · pattern ^[A-Z]{3}$ |
vertical | "general" | "electronics" | "fashion" | "beauty" | "grocery" | "home" | "toys" | "health" | "sports" | "books" | no | Store type: picks the word lists search uses. `general` = many kinds of products: the shared words of every store type, without words two types read differently. Set it with PATCH /v1/settings {"vertical": ...}.default "general" |
Responses
- 201Successful Response
TenantOut
GET
/v1/settingsStore settings
Needs a key or a dashboard session
Responses
- 200Successful Response
TenantSettings
PATCH
/v1/settingsSettings Update
Needs a key or a dashboard session
Request body application/json TenantSettings
| Name | Type | Required | Description |
|---|---|---|---|
name | string | null | no | max length 200 |
default_locale | string | null | no | pattern ^[a-z]{2}$ |
locales | string[] | null | no | |
currency | string | null | no | pattern ^[A-Z]{3}$ |
vertical | "general" | "electronics" | "fashion" | "beauty" | "grocery" | "home" | "toys" | "health" | "sports" | "books" | null | no | Store type. Sending a different value than the current one makes it the owner's choice (vertical_source owner: the catalog guess never changes it). Re-sending the current value changes nothing. |
vertical_source | "default" | "auto" | "owner" | null | no | Read only (ignored in PATCH). |
auto_detail | VerticalGuess | null | no | Read only (ignored in PATCH). |
timezone | string | null | no | max length 64 |
log_retention_days | integer | null | no | min 7 · max 730 |
search | SearchSettings | null | no | |
translation | TranslationSettings | null | no | |
weekly_report | boolean | null | no | |
extra | object | null | no |
Responses
- 200Successful Response
TenantSettings
GET
/v1/flagsFeature flags for this store
Needs a key or a dashboard session
Responses
- 200Successful Response
FlagOut[]
GET
/v1/onboardingOnboarding checklist progress
Needs a key or a dashboard session
Responses
- 200Successful Response
OnboardingOut
Data shapes on this page
TenantOut
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
slug | string | yes | |
name | string | yes | |
status | "pending_payment" | "trialing" | "active" | "past_due" | "suspended" | "canceled" | "deleted" | yes | pending_payment = a store without a plan: before its free trial or first payment, or after its free trial ended unpaid (see billing_state) |
plan_code | string | null | yes | The store's plan. null = no plan yet (billing_state trial_available, no_trial or trial_ended). |
billing_state | "trial_available" | "no_trial" | "trialing" | "trial_ended" | "paid" | "exempt" | no | trial_available: no plan; the 14-day free trial (no card) starts with the first search made with a public key. no_trial: no plan, and the owner already used the free trial on a store: choose a plan to go live. trialing: the free trial runs until trial_ends_at. trial_ended: the free trial ended unpaid; public keys answer 402 until a plan is chosen. paid: the store has a paid plan (see status). exempt: an internal store that billing never stops.default "paid" |
default_locale | string | yes | |
locales | string[] | yes | |
currency | string | yes | |
vertical | "general" | "electronics" | "fashion" | "beauty" | "grocery" | "home" | "toys" | "health" | "sports" | "books" | no | Store type: picks the word lists search uses. `general` = many kinds of products: the shared words of every store type, without words two types read differently. Set it with PATCH /v1/settings {"vertical": ...}.default "general" |
vertical_source | "default" | "auto" | "owner" | no | Where `vertical` came from: default (not set), auto (SeekGist guessed it from the catalog; checked again on full syncs), owner (chosen in settings; never changed by the guess).default "default" |
auto_detail | VerticalGuess | null | no | The last catalog check, when source is auto. |
trial_ends_at | string (date-time) | null | no | |
sync | SyncHealth | no | |
created_at | string (date-time) | yes |
VerticalGuess
The catalog check behind an automatic store type (`vertical_source: auto`).
| Name | Type | Required | Description |
|---|---|---|---|
vertical | "general" | "electronics" | "fashion" | "beauty" | "grocery" | "home" | "toys" | "health" | "sports" | "books" | yes | What the check decided: a store type, or general (no clear winner). |
leading | "general" | "electronics" | "fashion" | "beauty" | "grocery" | "home" | "toys" | "health" | "sports" | "books" | null | no | The most common store type among the products. |
share | number | yes | Share (0..1) of the checked products with a type that have the leading type. |
products_checked | integer | yes | |
products_decided | integer | yes | Checked products whose category or name points to one store type. |
checked_at | string (date-time) | null | no |
SyncHealth
The store's automatic product sync: when the last one came, and whether it has stopped.
| Name | Type | Required | Description |
|---|---|---|---|
last_sync_at | string (date-time) | null | no | The last automatic product sync: POST /v1/products/batch with a secret key (store modules, SDKs, your own server), a store app webhook or a connector pull sync. Dashboard file imports do not count. |
last_full_sync_at | string (date-time) | null | no | The last full sync (POST /v1/products/batch with sync_complete: true). |
stale | boolean | no | true: the store has done a full sync, but no automatic sync came for more than 26 hours (its daily job has probably stopped). Never true for a store without a full sync.default false |
TenantCreate
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | max length 200 |
slug | string | null | no | pattern ^[a-z0-9][a-z0-9-]{2,62}$ |
default_locale | string | no | default "en" · pattern ^[a-z]{2}$ |
locales | string[] | no | Catalog languages. |
currency | string | no | default "USD" · pattern ^[A-Z]{3}$ |
vertical | "general" | "electronics" | "fashion" | "beauty" | "grocery" | "home" | "toys" | "health" | "sports" | "books" | no | Store type: picks the word lists search uses. `general` = many kinds of products: the shared words of every store type, without words two types read differently. Set it with PATCH /v1/settings {"vertical": ...}.default "general" |
TenantSettings
| Name | Type | Required | Description |
|---|---|---|---|
name | string | null | no | max length 200 |
default_locale | string | null | no | pattern ^[a-z]{2}$ |
locales | string[] | null | no | |
currency | string | null | no | pattern ^[A-Z]{3}$ |
vertical | "general" | "electronics" | "fashion" | "beauty" | "grocery" | "home" | "toys" | "health" | "sports" | "books" | null | no | Store type. Sending a different value than the current one makes it the owner's choice (vertical_source owner: the catalog guess never changes it). Re-sending the current value changes nothing. |
vertical_source | "default" | "auto" | "owner" | null | no | Read only (ignored in PATCH). |
auto_detail | VerticalGuess | null | no | Read only (ignored in PATCH). |
timezone | string | null | no | max length 64 |
log_retention_days | integer | null | no | min 7 · max 730 |
search | SearchSettings | null | no | |
translation | TranslationSettings | null | no | |
weekly_report | boolean | null | no | |
extra | object | null | no |
SearchSettings
The tenant's saved ranking setup. RankingConfig (contract/merch.py) has the same field names, all optional, and overrides these per request (playground) or per A/B variant.
| Name | Type | Required | Description |
|---|---|---|---|
rule_parser | boolean | no | default true |
in_stock_first | boolean | no | default true |
business_signals | map<string, number> | no | Opt-in weights 0..1, e.g. {popularity: 0.2, margin: 0.1, clicks: 0.2}. |
typo_tolerance | boolean | no | default true |
hybrid_search | boolean | no | default false |
cheap_rerank_top_n | integer | no | default 50 · min 10 · max 200 |
merch_rules | boolean | no | default true |
disabled_rule_ids | string[] | no | |
synonym_sets | string[] | no | |
global_synonyms | boolean | no | Use the platform's global synonyms for my store type.default true |
disabled_global_synonym_ids | string[] | no | Global synonyms I switched off. |
TranslationSettings
Per-tenant translation setup (part of TenantSettings; PATCH /v1/settings). The feature flag `translation_watch` makes watch mode AVAILABLE; `watch` here turns it ON for this store.
| Name | Type | Required | Description |
|---|---|---|---|
watch | boolean | no | Translate new and changed products automatically.default false |
target_locales | string[] | no | |
fields | "name" | "description" | "category" | "attribute_name" | "attribute_value"[] | no | |
index_machine_translations | boolean | no | Search uses automatic translations that passed the automatic checks before review.default true |
FlagOut
| Name | Type | Required | Description |
|---|---|---|---|
key | string | yes | |
enabled | boolean | yes | |
source | "default" | "rollout" | "override" | "plan" | yes |
OnboardingOut
| Name | Type | Required | Description |
|---|---|---|---|
steps | OnboardingStep[] | yes | |
started_at | string (date-time) | yes | |
minutes_elapsed | number | yes |
OnboardingStep
| Name | Type | Required | Description |
|---|---|---|---|
key | "platform" | "connector" | "first_index" | "first_search" | "keys" | "team" | yes | |
done | boolean | yes | |
done_at | string (date-time) | null | no |