discoverGPT API Docs

Welcome to the developer documentation for discoverGPT — visualAI's unified REST API + MCP gateway for agency partners and developers. One platform, one set of credentials, four AI capabilities: search, data cleaning, feeds & GEO, and virtual try-on. This entire site is a single scrollable document — use the left sidebar to jump to any section.

Introduction

discoverGPT is a unified REST API and MCP gateway that exposes visualAI's four AI capabilities to agency partners and developers through one set of credentials and one canonical catalog.

What's included at every tier

Onboard once: shared ingest and enrichment mean every product you load flows into all four capabilities without per-capability setup. Each capability becomes available once its pipeline finishes — see How ingestion works.

What you can build

Search:

• Natural-language product search. Convert free-text queries like "something comfortable for a beach wedding under $200" into ranked product results.
• Precise-color search. Mix a text query with an RGB or named color and rank products by both semantic and precise-color similarity.
• Image-similarity search. Upload a reference image and return the closest matching products from your catalog.
• Personalized results. Layer optional shopper preferences — style, colors, size, budget — over any of the above.

Data cleaning:

• Batch enrichment. Submit raw products and get back cleaned titles, rewritten descriptions, and normalized attributes, ready to publish.
• Quality scoring. Surface thin, duplicated, or low-quality records before they reach your storefront or your feeds.

Feeds & GEO:

• AI-readable feeds. Generate Schema.org JSON-LD, an llms.txt summary, plus ACP and Perplexity Shopping feeds from one enriched catalog. The same catalog also backs a UCP (Universal Commerce Protocol) query API for agents that discover and query rather than download.
• Multi-protocol syndication. Distribute to ChatGPT, Gemini, Perplexity, and MCP-aware agents without betting on a single protocol.
• GEO dashboards. Track which products surface inside AI assistants and get recommendations to improve visibility.

Virtual try-on:

• AI image composition. Generate on-model and lifestyle images from product photos — no photoshoot required. Each compose call costs ~$0.18 pay-as-you-go, down to $0.10 at volume with prepaid credits — see Virtual Try-On.

Agent-native: built on MCP

Beyond REST, every capability above is also exposed through the Model Context Protocol (MCP) — the open standard that lets AI agents discover and call tools in a uniform way. Point an MCP-aware host (Claude, ChatGPT, Cursor, or your own agent) at discoverGPT's /mcp/sse endpoint and your catalog becomes a set of ready-to-use agent tools, with no glue code. See Model Context Protocol (MCP) for how it works and why it matters.

Platform-neutral by design

discoverGPT does not require Shopify. Every capability operates on a single canonical products table, and Shopify is one of several supported ways to populate it.

If your data lives in BigCommerce, WooCommerce, Magento, a custom PIM, a flat CSV export, or an S3 data lake, you can still use the API — see the Data Model and Ingesting Your Data sections for the canonical schema and available ingest paths.

Plans & Pricing

discoverGPT is gated by aggregate SKUs at the billing-account (agency) level — not per store. Stores, seats, and all four capabilities are unlimited at every tier.

Rules:

• The full platform is included at every tier, including Starter — every API and MCP tool: trimodal search, data enrichment, universal data feeds for agentic discovery, and virtual try-on.
• Every variant counts as a SKU. A product with 20 size/color variations is 20 SKUs — each variant is individually enriched, embedded, and searchable. Your SKU count is your total variant count across all connected stores.
• Unlimited stores on paid tiers (Growth and up); Starter includes 1 store. The SKU gate is always aggregate across all your stores, not per store.
• Unlimited seats.
• Virtual try-on (VTO) compose is the one usage meter: ~$0.18/compose pay-as-you-go, or prepaid credit packs down to $0.10/compose at volume. Each paid tier includes a monthly allotment — see Virtual Try-On for the full pricing ladder.
• Search, cleaning, feeds, and GEO run flat under a generous fair-use cap — exceeding it triggers an upgrade prompt, never a surprise invoice.

Where to start

Base URL

All API requests go to:

https://api.vairetail.com

This host is a placeholder — the final production endpoint is TBD and will be published here before GA.

Support

Questions about integration, enterprise access, or data migration? Email enterprise@vairetail.com or visit vairetail.com.

Platform overview

discoverGPT is one 34-claim patent-pending engine with four capability APIs in front of it. All four run on the same canonical products data model and the same ingest + enrichment pipeline — so a catalog you onboard once is usable by every capability.

The unified gateway

Each capability also maintains a direct service endpoint with its own base URL, sharing the same JSON conventions, error shapes, and — for direct endpoints — the X-Merchant-ID header. See Authentication for both auth modes. The direct-endpoint sections below (Quality, Feeds and Visibility, etc.) document that lower-level contract for reference — they are not a second way to reach the same data with today's published hostnames.

How they fit together

Used as a pipeline:

1. Ingest a catalog — Shopify pull, push ingest, CSV/JSON, or a custom source — into the canonical products model. See Ingesting Your Data.
2. Clean & enrich it: review AI-rewritten titles, descriptions, and attributes, then push approved changes back to the store.
3. Search it, syndicate it with feeds so AI agents can discover and quote your products, and compose hero imagery.

Used independently, each capability is a standalone HTTP API — adopt only what you need.

Jump to a capability

Model Context Protocol (MCP)

discoverGPT speaks two protocols over the same engine: a REST API for your own code, and MCP for AI agents. You don't have to choose — both run on the same account and canonical catalog (REST authenticates with client-credentials; MCP authorizes once via browser consent).

What MCP is

MCP (Model Context Protocol) is an open standard for connecting AI agents to tools and data — a universal adapter for AI. Instead of every agent author writing custom integration code against every API, an MCP-aware host — Claude, ChatGPT, Cursor, or a custom agent — connects to an MCP server, discovers its tools automatically, and calls them as the conversation requires.

Why we offer it

A growing share of shopping and merchandising will happen through AI agents. Without MCP, every agency building such an agent would hand-write REST calls, paginate results, reshape responses into something a model can reason over, and repeat that work for every AI host. With MCP, none of that is necessary — discoverGPT hands the agent ready-to-use tools backed by the same canonical catalog as the REST API.

How it works

  ┌───────────────────────────┐         ┌──────────────────────────────┐
  │  MCP-aware host            │   MCP   │  discoverGPT · /mcp (SSE)   │
  │  Claude · ChatGPT ·        │ ◄─────► │  one OAuth credential        │
  │  Cursor · your own agent   │  tools  │                              │
  └───────────────────────────┘         └───────────────┬──────────────┘
        discover + call tools                            │ tools run on the
                                                          ▼ same engine as REST
              ┌──────────────────────────────────────────────────────┐
              │  one canonical catalog →                              │
              │  Search · Cleaning · Feeds · Try-on                   │
              └──────────────────────────────────────────────────────┘

1. Your agent's host connects to https://api.vairetail.com/mcp/sse (SSE transport) and authorizes once through a browser consent screen — no API keys to copy or rotate (see MCP transport).
2. The host discovers discoverGPT's tools and exposes them to the model.
3. As the user converses, the model calls the tools — search, product detail, recommendations, brand context, feeds, quality — and discoverGPT runs them against the merchant's canonical catalog, returning agent-ready structured data (the same discovery + transaction shapes documented under Search API).

What it makes easier

For developers

• Zero glue code. The agent discovers and calls tools; you don't hand-write requests, pagination, or response reshaping.
• Agent-ready data. Tools return structured results designed for model reasoning and agentic checkout (the ACP transaction shape) — not raw rows.
• One integration, every host. The same MCP server works across Claude, ChatGPT, Cursor, and custom agents — no per-host rewrites.

For agencies

• Ship AI commerce agents fast. Stand up a shopping or merchandising agent for a merchant in hours, not weeks — one endpoint, one credential, all four capabilities as tools.
• Future-proof. As new MCP-aware hosts appear, your agent works on them with no changes.
• Bill once. MCP usage flows through the same account, tiers, and quotas as REST.

Tools exposed over MCP

Connection details — endpoint, transport, and auth — are in MCP transport under the Gateway API.

Quickstart

Go from zero to a live text + color search in under five minutes. Every new account starts on the free Starter tier with a read-only demo merchant already authorized for your keys — so the calls below return real results on your very first request, no catalog upload required.

1. Sign up

Create your account at developer.vairetail.com — the free Starter tier, no card. Self-serve signup provisions your org and the demo merchant automatically.

2. Create an API key

In the dashboard, open API Keys → Create key. You'll get a client_id and a client_secret.

export CLIENT_ID="YOUR_CLIENT_ID"
export CLIENT_SECRET="YOUR_CLIENT_SECRET"
export MERCHANT_ID="98334572911"   # the shared demo catalog

3. Exchange credentials for a token

Mint a short-lived Bearer token with the OAuth 2.0 client_credentials grant. The request is form-encoded; scope names the merchant you act on as merchant:{id}.

curl -s -X POST https://api.vairetail.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" \
  -d scope="merchant:$MERCHANT_ID"

Response:

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "merchant:98334572911"
}

Tokens expire after 15 minutes (re-mint on 401). Grab the token:

export TOKEN="eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."

4. Run a text + color search

Call POST /v1/search. This searches for a midi dress in a deep red.

curl -s -X POST https://api.vairetail.com/v1/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query_text": "midi dress",
    "query_color": { "space": "hsv", "values": [0, 90, 85] },
    "limit": 5
  }'

Python

import requests

BASE = "https://api.vairetail.com"
tok = requests.post(f"{BASE}/oauth/token", data={
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "scope": "merchant:98334572911",
}).json()

res = requests.post(f"{BASE}/v1/search",
    headers={"Authorization": f"Bearer {tok['access_token']}"},
    json={"query_text": "midi dress",
          "query_color": {"space": "hsv", "values": [0, 90, 85]},
          "limit": 5}).json()

for p in res["discovery"]:
    price = p["offers"][0]["price_cents"] / 100 if p["offers"] else None
    print(p["product_id"], p["name"], f"${price:.2f}" if price else "—")

JavaScript

const BASE = "https://api.vairetail.com";
const tokenRes = await fetch(`${BASE}/oauth/token`, {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: "YOUR_CLIENT_ID",
    client_secret: "YOUR_CLIENT_SECRET",
    scope: "merchant:98334572911",
  }),
});
const { access_token } = await tokenRes.json();

const searchRes = await fetch(`${BASE}/v1/search`, {
  method: "POST",
  headers: { Authorization: `Bearer ${access_token}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    query_text: "midi dress",
    query_color: { space: "hsv", values: [0, 90, 85] },
    limit: 5,
  }),
});
const { discovery } = await searchRes.json();
for (const p of discovery) {
  const price = p.offers[0] ? (p.offers[0].price_cents / 100).toFixed(2) : "—";
  console.log(p.product_id, p.name, `$${price}`);
}

A successful call returns a SearchResponse with discovery and transaction arrays:

{
  "discovery": [
    {
      "product_id": "8471290374",
      "name": "Satin Wrap Midi Dress",
      "brand": "Trendsi",
      "category": "Dresses",
      "images": [{ "url": "https://cdn.shopify.com/s/files/ruby-wrap-midi.jpg" }],
      "offers": [{ "price_cents": 6699, "currency": "USD", "availability": { "in_stock": true } }]
    }
  ],
  "transaction": [],
  "total": 5
}

That's it — you minted a token and ran a live text + color search against the demo catalog. Each discovery hit is an agent-ready product shape (product_id, name, images, offers).

5. Next steps

Legacy quickstart (direct product API)

If you integrated before the unified gateway launched, the direct search service is still active. Replace steps 1–3 above with:

curl -X POST \
  https://developer-search-devID.region.run.app/api/v0/product/search/text \
  -H "X-Merchant-ID: 12345" \
  -H "Content-Type: application/json" \
  -d '{
    "query_str": "comfortable linen shirt under $80",
    "limit": 5
  }'

See Authentication → Direct product API (legacy) for full details.

Wiring search into your storefront

vairetail gives you a search API, not a drop-in widget — you own the UX. A minimal search bar calls POST /v1/search from your backend (never expose your token to the browser) and renders the discovery array it returns.

// server route: POST /api/search  { q: string }
export async function search(req, res) {
  const r = await fetch("https://api.vairetail.com/v1/search", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VAIRETAIL_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query_text: req.body.q, limit: 20 }),
  });
  const data = await r.json();
  res.json(data.discovery ?? []);
}

// client: a search bar that renders results
function SearchBar() {
  const [results, setResults] = useState([]);
  async function onSubmit(q) {
    const r = await fetch("/api/search", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ q }),
    });
    setResults(await r.json());
  }
  return (
    <>
      <input onKeyDown={(e) => e.key === "Enter" && onSubmit(e.target.value)} />
      <ul>
        {results.map((p) => (
          <li key={p.product_id}>{p.name} — {p.brand}</li>
        ))}
      </ul>
    </>
  );
}

Want to try queries before writing code? Use the live search demo (no token needed), or the playground to hit /v1/search against the demo merchant with your own token.

Authentication

discoverGPT supports two authentication modes: OAuth 2.0 client-credentials (the primary mode for all gateway /v1/* endpoints) and the legacy X-Merchant-ID header (direct product-service endpoints, retained for backward compatibility).

OAuth 2.0 client-credentials (primary)

All gateway endpoints under /v1/* require a Bearer JWT obtained via the OAuth token endpoint.

Step 1 — request a token

POST /oauth/token HTTP/1.1
Host: api.vairetail.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=merchant:YOUR_MERCHANT_ID

Fields:

Response — 200 OK:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 900
}

The access_token is a JWT with a 15-minute TTL. Re-request a new token before it expires; do not cache it beyond expires_in seconds.

Step 2 — send Bearer on every request

POST /v1/search HTTP/1.1
Host: api.vairetail.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Every /v1/* endpoint requires this header. A missing or expired token returns 401 Unauthorized.

How to get credentials

Credentials (client_id / client_secret) are self-serve: sign up at developer.vairetail.com, then open API Keys → Create key in the dashboard (see Quickstart step 2). Keys are issued per agency, not per store. Email enterprise@vairetail.com only if you need something the dashboard cannot do — a custom plan, or an existing Shopify store adopted into your organization.

Direct product API (legacy)

The individual backend services accept an integer X-Merchant-ID header identifying your catalog. This mode is retained for backward compatibility and is documented here so integrations written against it remain valid.

POST /api/v0/product/search/text HTTP/1.1
Host: developer-search-devID.region.run.app
Content-Type: application/json
X-Merchant-ID: 12345

If the header is missing or non-integer, the server returns:

{ "detail": "Missing or invalid X-Merchant-ID header" }

with HTTP status 400.

Endpoints that do NOT require X-Merchant-ID

• GET /health — platform health check
• GET /api/v1/proxy-image — public image proxy

Every other Search API direct-service endpoint requires the header.

Endpoints that require more than X-Merchant-ID

A bare X-Merchant-ID is sufficient for the Search API above and for a few other direct endpoints (pipeline/status, synonyms/*). It is not sufficient for the following route families — a security fix closed the gap where a client-suppliable Shopify store ID (not a secret) was trusted as identity on its own:

These require Authorization: Bearer <session token> — the Shopify App Bridge session token the discoverGPT dashboard attaches automatically inside the embedded app — instead of, or in addition to, X-Merchant-ID. It is not something a third-party integration can construct standalone. Sent only X-Merchant-ID, these now return 401 with "Missing or invalid caller identity" (catalogGPT), "Missing or invalid credentials" (cleanerGPT), or "Missing session token" (generate-key specifically). Where the same data is reachable through the OAuth gateway instead, the linked section says so — most of these route families are not.

How merchant IDs are issued

• Shopify merchants: your merchant ID is provisioned automatically during the Shopify app install flow and stored in the theme extension's local storage as merchant_id.
• Non-Shopify merchants: merchant IDs are issued by the visualAI team during onboarding — contact enterprise@vairetail.com.

Trust model

The direct-service production API accepts requests only from approved origins via a CORS allow-list. The X-Merchant-ID header identifies which catalog to operate on; it does not itself authenticate the caller. This model is safe for the current browser-only deployment surface but is not suitable for server-to-server or cross-organization use. For server-to-server integrations, use the OAuth gateway.

Decoupling from Shopify

Today, a merchant's ID happens to equal their Shopify Shop ID for Shopify installs. This is an implementation detail and will change — new non-Shopify merchants already receive IDs from a separate range. Always treat the merchant ID as an opaque integer.

Errors

discoverGPT uses conventional HTTP status codes and returns all error details in a JSON body with a detail field.

Error shape

{
  "detail": "Missing or invalid X-Merchant-ID header"
}

detail is a human-readable string. In some validation errors it is a list of FastAPI validation objects — see Validation errors below.

Status codes

Common error examples

400 — missing merchant ID

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"detail": "Missing or invalid X-Merchant-ID header"}

400 — empty search body

Sent to POST /api/v0/product/search/textandcolor with neither a query_str nor a color:

{ "detail": "At least one of 'text' or 'color' must be provided." }

401 — missing verified caller identity

Sent to a route that requires more than a bare X-Merchant-ID (see Endpoints that require more than X-Merchant-ID) without a valid Authorization: Bearer <session token>. The exact message depends on which service and dependency rejected the request:

{ "detail": "Missing or invalid caller identity" }

{ "detail": "Missing or invalid credentials" }

{ "detail": "Missing session token" }

403 — cross-merchant access

Attempting to read another merchant's pipeline status:

{ "detail": "Access denied to this merchant's pipeline status" }

404 — resource not found

{ "detail": "User preferences not found" }

422 — validation error

{
  "detail": [
    {
      "loc": ["body", "query_str"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Retries

The search endpoints are idempotent — identical POSTs return identical results (and often a cached payload). Safe to retry on 5xx with exponential backoff.

Mutation endpoints (POST /api/v1/user/profile, POST /api/v1/user/preferences, PUT /api/v1/pipeline/status/{merchant_id}) are also safe to retry with the same body — they upsert based on their natural keys.

The DELETE /api/v1/merchant/{merchant_id}/data endpoint is not automatically retried and requires an explicit environment flag on the server; do not retry on a 403 for this endpoint.

Request ID

Every response includes an X-Request-ID header containing a UUID that uniquely identifies the request on the server side. Include this when reporting issues to enterprise@vairetail.com.

HTTP/1.1 200 OK
X-Request-ID: f2c8e9d1-0b3a-4a74-9cc6-b1d3a2a0f0ab

Data Model

discoverGPT operates on a small, fixed set of canonical tables. Every search, every recommendation, every preference query runs against these tables regardless of where your data originated.

Products

products is the single table every search endpoint reads. The model is variant-centric: it holds one row per variant (identified by variant_id), so a product with three sizes is three rows sharing a product_id. A product with no variants is a single row whose variant_id defaults to its product_id. Regardless of whether your data came from Shopify, a CSV export, or a custom PIM, discoverGPT reads it here.

Rows are scoped by merchant_id — multi-tenant isolation is enforced at the database level via row-level security.

Fields you provide

Fields we compute

These columns are populated by the discoverGPT ETL pipeline during ingest and enrichment. Do not provide them — sending them on ingest is an error.

Uniqueness & upserts

Rows are unique on (merchant_id, product_id, variant_id) — one row per variant. Ingesting a row whose (product_id, variant_id) already exists for the same merchant is treated as an upsert: non-null fields from the new payload overwrite the existing row, and the computed columns are recomputed in the next enrichment cycle. (For a product with no variants, variant_id defaults to product_id, so the key collapses to one row per product.)

Related reading

• CSV format — headers, sample file, type rules.
• JSON / NDJSON format — shapes for HTTP ingest.
• Column Mapper — paste your source headers, get a canonical mapping.

User profiles

user_profile holds optional per-shopper identity data. Every profile is scoped to a single merchant (merchant_id) and keyed by email within that merchant.

User profiles are optional. Anonymous search works perfectly well — you only need profiles when you want to attach preferences or personalize results over time.

Fields

Uniqueness

Rows are unique on (merchant_id, email_id). Creating a profile with an existing email returns the existing row rather than a duplicate — see POST /api/v1/user/profile.

Related endpoints

• POST /api/v1/user/profile
• POST /api/v1/user/profile/email

User preferences

user_preferences holds optional per-shopper preferences that search and recommendation endpoints use to personalize results. Each row is attached to a user_profile by user_profile_id, and has a one-to-one relationship with it.

Preferences are optional and independent of the rest of the catalog — you can ship discoverGPT with no preferences at all and still get a great baseline search experience.

Fields

How preferences are used

When a search request is made with preferences: true and a user_profile_id, the API loads that profile's preferences and:

1. Feeds conversational_style into the recommendation LLM.
2. Adds favorite_colors and fashion_material_prefer as soft ranking signals — products matching preferred attributes are nudged up.
3. Uses body_type, age_group, and personal_fashion_style as context in the recommendation text.

Preferences are never used as a hard filter — they influence ranking, they don't exclude products.

Related endpoints

• POST /api/v1/user/preferences
• POST /api/v1/user/preferences/update
• GET /api/v1/user/preferences/{user_profile_id}
• POST /api/v1/user/preferences/randomdata

Pipeline status

pipeline_status tracks the progress of a merchant's ingest and enrichment pipeline — from initial catalog import all the way through embedding generation and extension deployment. It is populated by discoverGPT's internal ETL workers and read by admin UIs to display onboarding progress.

You don't usually write to this table directly — the POST /api/v1/pipeline/status endpoint initializes a row, and the internal pipeline workers update it as each step completes. Your admin UI reads it via GET /api/v1/pipeline/status/{merchant_id}.

Fields

Response-only fields

The PipelineStatusResponse returned by the API endpoints adds two computed fields that are not stored in the database:

Pipeline steps

The default dev pipeline has these steps, in order:

1. shopify_etl_dev — initial catalog import (Shopify merchants only today)
2. enrichment_dev — description enrichment, category classification, gender inference
3. create_color_embeddings — extract and embed dominant colors
4. add_color_names — map color embeddings to human-readable color names
5. create_text_embeddings — generate semantic text embeddings
6. create_img_embeddings — generate image similarity embeddings
7. deploy_shoppergpt_extension — deploy the storefront extension (Shopify only)

Non-Shopify merchants use a modified pipeline that skips shopify_etl_dev and deploy_shoppergpt_extension.

CSV format

discoverGPT accepts UTF-8 CSV files whose columns map to the canonical products fields.

Requirements

• Encoding: UTF-8 (no BOM required, but accepted).
• Delimiter: comma (,).
• Header row: required. Column names must match the canonical field names exactly, or a mapping must be supplied.
• Quoting: RFC 4180 — wrap any field containing commas, quotes, or newlines in double quotes, with interior quotes doubled ("").
• Row order: unimportant. Rows will be imported in the order given.
• Max size: 100 MB per file for direct upload. For larger catalogs, split into multiple files or use NDJSON streaming.

Column mapping

If your source system uses different column names — and it almost certainly does — use the Column Mapper to paste your headers and produce a mapping.json file. You can then either:

1. Run the mapping yourself (Node or Python snippets) to produce a canonical CSV, or
2. Ship mapping.json alongside the raw CSV (once the push-ingest endpoint is GA).

Sample file

The template is a UTF-8 CSV with a header row; one row per product variant. Each column maps to a canonical products field — for the complete column-by-column reference (type, required/optional, allowed values, and data formats for every field) see Products → Fields you provide. Column order doesn't matter; header names do (case-insensitive, matched to canonical names or mapped). Data-format essentials:

• Required in every row: product_id, product_name, price, price_numeric, image1.
• Prices: price is a currency-formatted string ("69.00"); price_numeric is a bare non-negative decimal (69.00) used for filtering and ranking. There are no date columns — timestamps are database-managed.
• Variants: a product with variants is multiple rows sharing one product_id, each with its own variant_id and option*_value. Omit variant_id for a no-variant product and it defaults to product_id.
• Lists: tags is comma-separated inside one quoted cell.

A minimal canonical CSV — note SKU-1001 appears twice (two size variants), and SKU-1002 omits variant_id (single-variant product):

product_id,variant_id,product_name,handle,product_details,brand,category,color,tags,price,price_numeric,option1_name,option1_value,gender,image1,status
SKU-1001,SKU-1001-M,Relaxed Linen Button-Up,relaxed-linen-button-up,"Breezy 100% linen with a relaxed cut.",Cove & Coast,tops,white,"linen,summer",69.00,69.00,Size,M,mens,https://cdn.example.com/images/relaxed-linen.jpg,active
SKU-1001,SKU-1001-L,Relaxed Linen Button-Up,relaxed-linen-button-up,"Breezy 100% linen with a relaxed cut.",Cove & Coast,tops,white,"linen,summer",69.00,69.00,Size,L,mens,https://cdn.example.com/images/relaxed-linen.jpg,active
SKU-1002,,Classic Chinos,classic-chinos,"Midweight cotton chinos with a tailored leg.",Cove & Coast,bottoms,khaki,"cotton,classic",89.00,89.00,Size,32,mens,https://cdn.example.com/images/classic-chinos.jpg,active

Download the full sample: products.csv

Validation rules

During ingest discoverGPT applies the following rules to every row:

• product_id, product_name, price, price_numeric, and image1 must be present and non-empty.
• price_numeric must parse as a non-negative float.
• image1 must be a valid HTTPS URL.
• status, if provided, must be one of active, draft, archived.
• display_flag, if provided, must be true or false (case-insensitive).
• gender, if provided, must be one of mens, womens, unisex, kids.
• Any additional columns not in the canonical schema are placed into metadata_json as string values.

Rows that fail validation are skipped with a line number and a reason in the ingest log; valid rows in the same file still import.

JSON format

This section covers file ingest / bulk upload shapes only — not the POST /v1/ingest push body. For bulk file uploads, discoverGPT accepts two JSON shapes: newline-delimited JSON (NDJSON) and an array of objects. For any catalog over a few thousand rows, prefer NDJSON — it streams and doesn't require the whole catalog to live in memory on either side.

The push endpoint (POST /v1/ingest) does not accept NDJSON or a bare array; its body is a single {"products": [...]} JSON object. See Push ingest → Contract for the exact accepted fields.

NDJSON (preferred for large catalogs)

One JSON object per line. No array brackets, no trailing commas. UTF-8. Content-type application/x-ndjson.

{"product_id":"SKU-1001","variant_id":"SKU-1001-M","product_name":"Relaxed Linen Button-Up","handle":"relaxed-linen-button-up","product_details":"Breezy 100% linen with a relaxed cut.","brand":"Cove & Coast","category":"tops","color":"white","tags":"linen,summer","price":"69.00","price_numeric":69.0,"option1_name":"Size","option1_value":"M","gender":"mens","image1":"https://cdn.example.com/images/relaxed-linen.jpg","status":"active"}
{"product_id":"SKU-1001","variant_id":"SKU-1001-L","product_name":"Relaxed Linen Button-Up","handle":"relaxed-linen-button-up","product_details":"Breezy 100% linen with a relaxed cut.","brand":"Cove & Coast","category":"tops","color":"white","tags":"linen,summer","price":"69.00","price_numeric":69.0,"option1_name":"Size","option1_value":"L","gender":"mens","image1":"https://cdn.example.com/images/relaxed-linen.jpg","status":"active"}

Download the full sample: products.ndjson

Array-of-objects (small batches)

For small imports (under a few thousand products), a standard JSON array works fine. Content-type application/json.

[
  {
    "product_id": "SKU-1001",
    "product_name": "Relaxed Linen Button-Up",
    "handle": "relaxed-linen-button-up",
    "product_details": "Breezy 100% linen with a relaxed cut.",
    "brand": "Cove & Coast",
    "category": "tops",
    "color": "white",
    "tags": "linen,summer",
    "price": "69.00",
    "price_numeric": 69.0,
    "gender": "mens",
    "image1": "https://cdn.example.com/images/relaxed-linen.jpg",
    "status": "active"
  },
  {
    "product_id": "SKU-1002",
    "product_name": "Classic Chinos",
    "handle": "classic-chinos",
    "product_details": "Midweight cotton chinos with a tailored leg.",
    "brand": "Cove & Coast",
    "category": "bottoms",
    "color": "khaki",
    "tags": "cotton,classic",
    "price": "89.00",
    "price_numeric": 89.0,
    "gender": "mens",
    "image1": "https://cdn.example.com/images/classic-chinos.jpg",
    "status": "active"
  }
]

Type coercion

• Strings vs numbers: price must be a JSON string; price_numeric must be a JSON number. These are separate fields for a reason — the numeric version is what search uses, the string version is what the UI renders.
• Booleans: display_flag must be a JSON boolean, not "true" as a string.
• Arrays: tags must be a string (comma-separated). It is stored that way in the database and split at query time only when needed.
• Unknown fields: any field not in the canonical schema is written to metadata_json.

Fields you must not include

Never include these computed fields on ingest — the server will reject them:

• merchant_id (set server-side from auth)
• id, last_updated (database-managed)
• text_embedding, text_embedding_1, img_embedding, image_desc_embed
• color_embedding, color_embedding_1, color_embedding_2, color_embedding_3
• color_hsv_embedding_1, color_hsv_embedding_2, color_hsv_embedding_3
• percent_1, percent_2, percent_3

See products → Fields we compute.

How ingestion and orchestration works

Your catalog moves through a two-tier pipeline. You only ever choose outcomes — the platform runs the right jobs, in the right order, and skips anything already done.

The two tiers

Foundation (runs once per store, then reused). When a catalog first arrives, two foundation steps run: import (your products land in the catalog) and enrichment (category, gender, sub-category, enriched tags, and an AI vision description of each product image). Enrichment is vertical-aware — it classifies any product type, not just apparel; gender defaults to unisex outside apparel, and non-apparel products get a per-vertical attribute bag (material, style, room, medium, and similar, depending on category) written to metadata_json. Foundation runs a single time per store — if you use more than one vairetail product, the second and third reuse the first's foundation instead of re-importing or re-enriching.

Outcomes (you choose these). On top of the foundation, you turn on the capabilities you want. Each maps to a set of jobs:

* Runs automatically once the catalog feed compiles; it comes with the Catalog feed outcome and isn't scheduled on its own.

Requesting Generate Q&A runs narrative generation first automatically if you haven't also requested Generate narratives — you don't need to request both.

One ordering rule worth knowing

If you enable natural-language search together with precise-color search, color runs first and NL runs last — on purpose. The natural-language index embeds each product's color name (produced by the color step) directly into the searchable text, so a query like "navy blazer" matches on the color word. Enable color before (or with) NL and the platform orders it for you; enable NL alone and it still works, just without color words baked into the text index. Image search is independent — it lives in its own vector space and does not change NL quality. Enrichment (including the vision description that also strengthens NL) always runs first, underneath everything.

You won't step on your own data

Requesting an outcome runs only the work that's missing. Foundation and any enrichment another vairetail product already produced are reused, never re-run, and never overwritten. Re-requesting an outcome later safely backfills only what isn't done yet. You never have to sequence jobs yourself or worry about clobbering existing results.

Dos and don'ts

• Do ask for outcomes, not jobs. Don't try to trigger individual pipeline steps.
• Do expect a short pending window — an outcome is ready once its jobs finish, not the instant ingest returns. Poll pipeline status.
• Do turn on color search before or with natural-language search if you want color-aware text results.
• Don't assume a product is color- or image-searchable just because text search works — each outcome is independent (the one link is color → richer NL).
• Re-requesting is safe — it fills only the gaps.

Reliability & operational visibility

What actually happens when something fails, and how you'd find out — stated plainly rather than as a general resilience claim.

Retrying is safe. Every pipeline step is claimed exactly once per merchant before it runs — a duplicate webhook delivery, a retried request, or re-running ingest against a catalog you've already sent cannot cause a step to double-execute. Re-requesting an outcome "fills only the gaps" (above) for the same reason: the platform checks what's already done before doing anything.

Keeping data current is a re-sync, not a wait. For Shopify-installed apps this is automatic — see Webhook delivery & retry behavior above. For catalogs you push yourself, there's no background process that notices your source data changed on its own; call ingest again with the changed rows (or the outcomes you want refreshed) and only the gap gets processed. We'd rather say that plainly than claim a uniform automatic-freshness guarantee across every ingest path — explicit re-sync is the reliable way to keep push-ingested data current today.

Monitoring is pull, not push, today. GET /api/v1/pipeline/status/{merchant_id} is the source of truth for running / completed / failed and failed_steps — poll it after ingest, the same way the dashboard itself does. There's no email or in-app alert on pipeline failure yet and no outbound webhook to notify your systems (see the callout above) — if you need proactive alerting, build it on top of polling this endpoint for now.

Deletions require an explicit call. Removing a product from your source doesn't remove it from the canonical catalog on its own — see deletion-sync for the exact behavior and DELETE /api/v1/merchant/{merchant_id}/data for full removal.

Rate limits are usage-tier, not request-per-minute. See Plans & Pricing — every tier runs under a fair-use cap rather than a hard per-minute limit; exceeding it prompts an upgrade rather than throttling mid-request.

Ingesting Your Data

discoverGPT supports two ingest models: pull (discoverGPT reaches into your commerce platform on a schedule) and push (you send us your catalog). Pull is available today for Shopify; push is live today with six selectable outcomes — see How ingestion works.

Shopify (Pull)

The Shopify integration is the most common ingest path and the one available today. It is also the only ingest path that requires zero custom code on your side.

What it does

1. You install the discoverGPT app from the Shopify App Store.
2. You grant the app read access to your products and storefront.
3. discoverGPT pulls your product catalog via the Shopify Admin API and populates the canonical products table.
4. The enrichment pipeline runs: categories, color extraction, embeddings.
5. discoverGPT installs a theme extension that wires the search UI into your storefront. Semantic search goes live for shoppers once the search pipeline finishes (typically minutes after import); track it via pipeline status.
6. Ongoing updates stream in via Shopify webhooks — product creates, updates, and deletes are reflected in the canonical table within seconds.

Webhook delivery & retry behavior

Webhook processing retries automatically on failure with exponential backoff — starting at 1 second, doubling each attempt, capped at 5 minutes between tries. A transient failure on our side (a deploy, a database blip) does not lose the update; it's picked up on the next successful attempt.

Field mapping (Shopify → canonical)

Gender is inferred during enrichment from product_name, product_type, and body_html — non-apparel products default to unisex rather than a fabricated value. Color is extracted from image1 if not present in tags. Non-apparel products also get a per-vertical attribute bag (material, style, room, medium, and similar, depending on category) written to metadata_json — Shopify sells far more than apparel, and enrichment classifies whatever you send it.

Onboarding status

Pipeline progress (shopify_etl_dev → enrichment_dev → ... → deploy_shoppergpt_extension) is tracked in pipeline_status and can be read via GET /api/v1/pipeline/status/{merchant_id}.

Merchant ID

Your discoverGPT merchant_id is assigned during install and happens to equal your Shopify Shop ID for today's installs. Always treat it as an opaque integer — future non-Shopify merchant IDs will come from a separate range.

Uninstall

Uninstalling the Shopify app removes the theme extension and stops the webhook stream. Product rows remain in the canonical table by default (so reinstalling a week later doesn't require a full re-import).

For full data deletion on uninstall, see DELETE /api/v1/merchant/{merchant_id}/data.

Push ingest

Push ingest lets you send catalog rows to discoverGPT from any source — BigCommerce, WooCommerce, Magento, a custom PIM, a Python script reading from Snowflake, whatever.

Contract

POST /v1/ingest HTTP/1.1
Host: api.vairetail.com
Content-Type: application/json
Authorization: Bearer <access_token>

Body: a single JSON object with products (array, 1–1000 items) and outcomes (array of strings, at least one — see Outcomes for the valid values). The top-level object rejects unknown keys — there are no query parameters or form fields, only this JSON body.

Each product requires product_id (string). Recognized fields: variant_id (distinguishes variants of the same product; defaults to product_id if omitted — one row per product), handle, product_name, description, image_url, category, sub_category, brand, tags. Note the names — it's description, not product_details; image_url, not image1. Extra fields beyond these are accepted and passed through, but only the fields above are guaranteed to map to the canonical catalog.

Response

{
  "job_id": "sgpt-upsert-12345-4810",
  "accepted_product_count": 4810,
  "run_id": "push-8f3d2e1a-....",
  "outcome_errors": {}
}

Ingest returns once your rows are accepted (written synchronously); the outcomes you requested then run asynchronously. Track progress via GET /v1/ingest/runs/{run_id} (below) or pipeline status. See How ingestion works for what each outcome runs.

outcome_errors maps an outcome to a failure reason if the gateway couldn't forward your products to that outcome's backend — an outcome listed here was never dispatched, but every other requested outcome still processes normally.

Rows that fail validation are rejected and do not count toward accepted_product_count. dry_run (validate without writing) is not yet supported — planned, but not accepted today.

Check push-run status

GET /v1/ingest/runs/{run_id}

{
  "run_id": "push-8f3d2e1a-....",
  "status": "running",
  "outcomes": {
    "nl_search": "ready",
    "clean_data": "running"
  }
}

Each outcome you requested reports its own status: queued, running, ready, or failed. status at the top level reflects the run as a whole.

Running a mapping client-side

If you'd rather produce the canonical {"products":[...]} JSON body yourself before calling the ingest endpoint, see:

• Using the mapper output (Node)
• Using the mapper output (Python)

Example

curl -X POST https://api.vairetail.com/v1/ingest \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"outcomes":["nl_search"],"products":[{"product_id":"SKU-1","variant_id":"SKU-1-blue","product_name":"Aurora Linen Tee","description":"Lightweight linen tee","image_url":"https://example.com/tee.jpg","category":"Apparel","brand":"Aurora"}]}'

Other platforms

If your catalog lives somewhere other than Shopify, the path today is:

1. Export your catalog to CSV or NDJSON.
2. Use the Column Mapper to map your source columns to the canonical products schema.
3. Apply the mapping to produce a canonical file (Node or Python snippets).
4. Send it to us via push ingest or share it with the visualAI team during onboarding.

Below are the typical field mappings for the common platforms. These are seeded into the Column Mapper's auto-suggest.

BigCommerce

WooCommerce

Magento

Custom PIM / flat export

If you own the source format, the fastest path is to export a CSV whose headers already match the canonical schema. See CSV format for the required columns.

If you can't rename columns at the source, use the Column Mapper — paste your headers, accept the auto-suggestions, download mapping.json, and run it through the Node or Python transformer.

File ingest API (CSV and XLSX)

Unlike Push ingest above, which sends canonical JSON, file ingest lets you upload a .csv or .xlsx file directly and the gateway auto-detects your column mapping, runs the import as an async job, and reports per-row results — no NDJSON transform required. All endpoints below require Authorization: Bearer <jwt> — see Authentication for how to mint one.

Upload a file

POST /v1/ingest/file

Starts an async ingest job from an uploaded file. The gateway auto-detects a column mapping from header synonyms (e.g. handle → product_id, sku → variant_id, title → product_name, msrp → price); pass an explicit mapping to override individual fields, or a saved template_id to reuse an agency-wide mapping. Precedence is explicit mapping > template_id > auto-detected, merged field-by-field.

Headers

Request body (multipart form fields)

Target fields: product_id (required — the upload is rejected with 400 if it can't be resolved by explicit mapping, template, or auto-detection), variant_id (distinguishes variants of the same product; defaults to product_id if omitted), product_name, description, price, currency, image_url, additional_image_urls (|-delimited in the source column), product_url, category, sub_category, brand, tags. Any source column not consumed by the mapping is passed through under its normalized header name.

Response — 202 Accepted

{
  "job_id": "6f1b1a2e-8c3d-4e9a-9d1a-2b7c9e6f1234",
  "detected_mapping": {
    "product_id": "Handle",
    "variant_id": "SKU",
    "product_name": "Title",
    "price": "Price (USD)",
    "image_url": "Image URL"
  },
  "estimated_rows": 4821,
  "sample_rows": [
    {
      "product_id": "SKU-1001",
      "product_name": "Relaxed Linen Button-Up",
      "price": 69.0,
      "image_url": "https://cdn.example.com/images/relaxed-linen.jpg"
    }
  ],
  "headers": ["SKU", "Title", "Price (USD)", "Image URL"],
  "outcome_errors": {}
}

• detected_mapping — the mapping that will actually be used, keyed by canonical target field.
• sample_rows — up to 20 transformed preview rows. A row that would be skipped by the real import (e.g. an empty product_id) is simply omitted from the preview.
• headers — the raw column headers read from the file — handy for building your own mapping UI on top of this response.
• estimated_rows — total data rows parsed from the file.

Example

curl -X POST https://api.vairetail.com/v1/ingest/file \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@catalog.csv" \
  -F 'outcomes=["nl_search"]' \
  -F 'mapping={"product_id":"SKU","product_name":"Title"}'

import httpx

with open("catalog.csv", "rb") as f:
    r = httpx.post(
        "https://api.vairetail.com/v1/ingest/file",
        headers={"Authorization": f"Bearer {token}"},
        files={"file": ("catalog.csv", f, "text/csv")},
        data={
            "outcomes": '["nl_search"]',
            "mapping": '{"product_id":"SKU","product_name":"Title"}',
        },
    )
job_id = r.json()["job_id"]

const form = new FormData();
form.append('file', fileInput.files[0]);
form.append('outcomes', JSON.stringify(['nl_search']));
form.append('mapping', JSON.stringify({ product_id: 'SKU', product_name: 'Title' }));

const res = await fetch('https://api.vairetail.com/v1/ingest/file', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}` },
  body: form,
});
const { job_id } = await res.json();

Errors

Check ingest job status

GET /v1/ingest/file/{job_id}

Response — 200 OK

{
  "job_id": "6f1b1a2e-8c3d-4e9a-9d1a-2b7c9e6f1234",
  "state": "partial",
  "processed": 4821,
  "total": 4821,
  "skipped": 3,
  "accepted_product_count": 4818,
  "errors": [
    { "row": 142, "reason": "empty product_id" }
  ],
  "error_report_uri": "https://storage.googleapis.com/.../ingest/6f1b1a2e.../errors.json",
  "run_id": "push-8f3d2e1a-....",
  "outcome_errors": {}
}

• state — queued → running → terminal: succeeded (no skipped rows), partial (some rows skipped), or failed (the job itself errored).
• errors — up to 100 entries inline as { row, reason }. error_report_uri holds the complete list once the job finishes.
• run_id — identifies the push-run for your requested outcomes; poll it via GET /v1/ingest/runs/{run_id}. null until at least one product has been accepted, and permanently null for a failed job or one where every row was skipped.
• outcome_errors — maps an outcome to a failure reason if the gateway couldn't forward your accepted products to that outcome's backend; every other requested outcome still processes normally.

Example

curl https://api.vairetail.com/v1/ingest/file/$JOB_ID \
  -H "Authorization: Bearer $TOKEN"

Errors

Save a mapping template

POST /v1/ingest/mappings

Persists a reusable, agency-scoped column mapping so you don't have to resend an explicit mapping JSON blob on every upload — pass its id as template_id on Upload a file. Templates are agency-wide (not merchant-specific).

Request body

Response — 201 Created

{ "id": "9a4e2f10-6b3c-4a1d-8e7f-1234567890ab" }

Example

curl -X POST https://api.vairetail.com/v1/ingest/mappings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme PIM export",
    "mapping": { "product_id": "SKU", "product_name": "Title", "price": "Price (USD)" }
  }'

Errors

List mapping templates

GET /v1/ingest/mappings

Response — 200 OK

{
  "templates": [
    {
      "id": "9a4e2f10-6b3c-4a1d-8e7f-1234567890ab",
      "name": "Acme PIM export",
      "mapping": { "product_id": "SKU", "product_name": "Title", "price": "Price (USD)" },
      "created_at": "2026-07-01T12:00:00Z"
    }
  ]
}

Example

curl https://api.vairetail.com/v1/ingest/mappings \
  -H "Authorization: Bearer $TOKEN"

Create a merchant

Every account starts with only the shared demo catalog (98334572911), which is read-only. Before you can ingest anything you need a merchant of your own.

It is self-serve and takes one click:

1. Open Merchants in the dashboard
2. Click Create merchant
3. Copy the merchant id it returns

The new merchant is authorized for your existing API keys immediately — no new credentials, no waiting on us. From then on, scope your token to that id (scope=merchant:<your merchant id>) instead of the demo catalog, and every route in this reference works against your own catalogue.

Ingest quickstart

Zero to ingested: mint a token, upload a CSV, poll the job, and confirm the result. If you haven't created an API key yet, do Quickstart steps 1–2 first, and create a merchant if you have not already — the demo catalog cannot be written to.

{ "error": "demo_merchant_read_only",
  "message": "the shared demo catalog is read-only; create your own merchant to ingest data" }

1. Mint a token scoped to your merchant

export CLIENT_ID="YOUR_CLIENT_ID"
export CLIENT_SECRET="YOUR_CLIENT_SECRET"
export MERCHANT_ID="YOUR_MERCHANT_ID"   # one of your own merchants — NOT the demo catalog

curl -s -X POST https://api.vairetail.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET" \
  -d scope="merchant:$MERCHANT_ID"

export TOKEN="eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."   # access_token from the response

2. Upload your CSV

curl -s -X POST https://api.vairetail.com/v1/ingest/file \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@catalog.csv"

{
  "job_id": "6f1b1a2e-8c3d-4e9a-9d1a-2b7c9e6f1234",
  "detected_mapping": { "product_id": "Handle", "variant_id": "SKU", "product_name": "Title", "price": "Price (USD)" },
  "estimated_rows": 4821,
  "sample_rows": [{ "product_id": "shirt-relaxed-linen", "product_name": "Relaxed Linen Button-Up" }],
  "headers": ["Handle", "SKU", "Title", "Price (USD)"]
}

{ "detail": "required field 'product_id' is not mapped to any column" }

curl -s -X POST https://api.vairetail.com/v1/ingest/file \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@catalog.csv" \
  -F 'mapping={"product_id":"SKU","product_name":"Title","price":"Price (USD)"}'

Check detected_mapping before moving on. If it's missing a field you care about or mapped one wrong, re-upload with an explicit mapping JSON blob (or save a template and pass template_id) rather than proceeding with a bad mapping.

export JOB_ID="6f1b1a2e-8c3d-4e9a-9d1a-2b7c9e6f1234"   # job_id from the response

3. Poll until the job is terminal

import time
import httpx

BASE = "https://api.vairetail.com"
headers = {"Authorization": f"Bearer {token}"}

while True:
    status = httpx.get(f"{BASE}/v1/ingest/file/{job_id}", headers=headers).json()
    print("state:", status["state"], "processed:", status["processed"], "/", status["total"])
    if status["state"] in ("succeeded", "partial", "failed"):
        break
    time.sleep(2)

Or poll by hand with curl every couple of seconds:

curl -s https://api.vairetail.com/v1/ingest/file/$JOB_ID \
  -H "Authorization: Bearer $TOKEN"

4. Confirm the result

{
  "job_id": "6f1b1a2e-8c3d-4e9a-9d1a-2b7c9e6f1234",
  "state": "succeeded",
  "processed": 4821,
  "total": 4821,
  "skipped": 0,
  "accepted_product_count": 4821,
  "errors": [],
  "error_report_uri": null
}

state: "succeeded" with skipped: 0 means every row was accepted. A partial state with skipped > 0 isn't a failure — inspect errors (or error_report_uri for the full list), fix the source rows, and re-upload; the upsert-by-product_id semantics make re-running safe.

Column mapping & templates

This section covers the mapping engine behind Upload a file — the auto-detect logic, override precedence, and per-field coercion rules that decide what detected_mapping looks like on every upload. It's a different (smaller) schema than the full products table used by Push ingest and CSV format: file ingest doesn't require your columns to match canonical names at all — anything it doesn't recognize is passed through unchanged rather than rejected.

Canonical target schema

Any source column not consumed by the resolved mapping still makes it into the transformed row — it's passed through under its own normalized header (lowercased, punctuation stripped, internal whitespace collapsed to single spaces), so "Fabric %" becomes the key fabric. Nothing in your file is silently dropped.

Auto-detect synonyms

When you don't pass an explicit mapping or template_id, the gateway matches your file's headers against a synonym table in two passes: an exact pass (normalized header text equals a synonym) runs across every target field first, then a prefix pass (normalized header starts with a synonym plus at most one trailing word — "Price (USD)" normalizes to "price usd" and matches price) picks up whatever's left. Running exact matching to completion before any prefix matching starts means a field's exact synonym is never stolen by a looser prefix match on another field — e.g. "Product Type" is an exact synonym of category, and although it would also prefix-match product_name's "product" synonym, category claims it in the exact pass before that prefix match ever gets a chance.

Mapping precedence

Override precedence is explicit mapping > template_id > auto-detect, merged field-by-field — not a whole-mapping replacement. For example, given headers ["SKU", "Title"], an explicit mapping: {"product_name": "SKU"}, and a template mapping {"product_name": "Title"}:

• product_id comes from auto-detect ("SKU" — nothing else set it).
• product_name comes from the explicit mapping ("SKU"), even though the template also set it — explicit always wins per field.

Price coercion

price values are coerced to a number: a leading $ and thousands-separator commas are stripped, then the remainder is parsed as a float ("$1,299.00" → 1299.0). If the cleaned value doesn't parse as a number, the original string is kept as-is rather than the row being dropped or flagged as an error — a bad price never causes a row to be skipped. Only an empty product_id does that (recorded in the job's errors, see Check ingest job status).

Additional image URLs

additional_image_urls maps from a single source column whose value is |-delimited — "a.jpg|b.jpg|c.jpg" becomes ["a.jpg", "b.jpg", "c.jpg"]. The delimiter is fixed at | and isn't configurable via the API today.

If your source spreads gallery images across separate columns instead (image2, image3, … imageN) rather than one delimited column, those aren't auto-merged — none of them match the additional_image_urls synonyms above, so each passes through individually under its own normalized header rather than collapsing into additional_image_urls. Concatenate them into one |-delimited column before uploading (or map one of them explicitly) if you want a single additional_image_urls array.

Mapping templates

Save a mapping you like as a reusable, agency-scoped template with POST /v1/ingest/mappings, then apply it on any later upload with template_id instead of resending the JSON blob — see Save a mapping template and List mapping templates for full request/response shapes. Template names must be unique within your agency (409 on a duplicate); templates are agency-scoped, not merchant-scoped, so the same template applies across every merchant your agency ingests for. The dashboard wizard below is the easiest way to build and save one interactively.

Ingest from the dashboard

The dashboard wraps File ingest API in a three-step wizard — upload → review mapping → confirm & track — for teams who'd rather not script it. It's not a separate ingest path: uploads go through token-gated /internal/ingest/* routes that call the exact same mapping/job machinery as POST /v1/ingest/file, so they're metered identically to the API — there's no quota advantage to using the UI.

1. Upload

Open Ingest in the dashboard sidebar (/dashboard/ingest), pick one of your organization's authorized merchants from the dropdown (authorize one on the Merchants page first if the list is empty), choose a .csv or .xlsx file, and check at least one of Natural-language search, Color search, or Image search — these map directly to the API's outcomes field (see Upload a file) and control which search capabilities your catalog gets indexed for once the job completes. Upload & preview stays disabled until a merchant, a file, and at least one outcome are all set.

Clicking Upload & preview creates the ingest job immediately, using whatever mapping the gateway auto-detects from your file's headers, and publishes a push-run for your chosen outcomes once the job finishes accepting at least one product (see Check ingest job status's run_id).

2. Review the detected mapping

The map step shows every canonical field next to a <select> pre-filled with the auto-detected source column, a preview of the first 20 transformed rows in canonical shape, and quick stats (e.g. "92% of sampled rows have a price"). You can:

• Change any field's source column from the dropdown of your file's raw headers.
• Load a saved template from the template selector — it merges the template's mapping into your current selections.
• Save the current selections as a new template by naming it and clicking "Save as template" (agency-scoped; a duplicate name returns a 409, surfaced inline).

3. Confirm & track progress

Confirm & track progress is disabled until product_id is mapped. Once confirmed, the wizard polls the job's status every 3 seconds until it reaches a terminal state, showing:

• A progress bar (processed / total rows).
• A state pill (queued, running, succeeded, partial, failed).
• On completion: an accepted/skipped/total summary and, if any rows were skipped, the error_report_uri and a table of the first 100 row errors ({ row, reason }) — same data as Check ingest job status.

If status checks fail repeatedly (five in a row) — or the job disappears entirely (404) — polling stops and shows a Retry button. That only pauses the live view; the ingest job itself keeps running server-side regardless. Once the job reaches a terminal state, "Start a new upload" resets the wizard to step 1.

Column Mapper

The Column Mapper is an interactive tool that maps your source catalog columns to the canonical products schema. It runs entirely in your browser — nothing is uploaded. Once you've exported a mapping.json, use one of the recipes below to transform your raw CSV into a canonical {"products": [...]} payload.

Apply a mapping (Node.js)

This snippet takes a mapping.json file (downloaded from the Column Mapper) and uses it to convert a raw source CSV into a canonical {"products": [...]} payload ready for push ingest.

Install dependencies

npm install csv-parse

Script

import fs from 'node:fs';
import { parse } from 'csv-parse/sync';

// 1. Load the mapping file produced by the Column Mapper.
const mappingConfig = JSON.parse(fs.readFileSync('mapping.json', 'utf8'));
const { mapping } = mappingConfig;

// 2. Read the raw CSV.
const rawCsv = fs.readFileSync('raw-products.csv', 'utf8');
const rows = parse(rawCsv, { columns: true, skip_empty_lines: true });

// 3. Transform each row into the canonical shape.
const canonical = rows.map((row) => {
  const out = {};
  for (const [canonicalField, spec] of Object.entries(mapping)) {
    if (typeof spec === 'string') {
      out[canonicalField] = row[spec];
    } else {
      const value = row[spec.source];
      out[canonicalField] = applyTransform(value, spec.transform);
    }
  }
  return out;
});

// 4. Wrap in the push-ingest request body and write as JSON.
const payload = { products: canonical };
fs.writeFileSync('products.json', JSON.stringify(payload));

console.log(`Wrote ${canonical.length} canonical products`);

function applyTransform(value, transform) {
  if (value == null || value === '') return null;
  switch (transform) {
    case 'parse_float': {
      const n = parseFloat(String(value).replace(/[^0-9.-]/g, ''));
      return Number.isFinite(n) ? n : null;
    }
    case 'trim':
      return String(value).trim();
    case 'uppercase':
      return String(value).toUpperCase();
    case 'lowercase':
      return String(value).toLowerCase();
    case 'strip_html':
      return String(value).replace(/<[^>]*>/g, '');
    default:
      return value;
  }
}

Output

products.json will contain a single JSON object, {"products": [...]}, ready to be POSTed to the push-ingest endpoint.

Rows that fail validation are rejected and do not count toward accepted_product_count — dry_run is not yet supported (planned).

Apply a mapping (Python)

This snippet takes a mapping.json file (downloaded from the Column Mapper) and uses it to convert a raw source CSV into a canonical {"products": [...]} payload, ready for push ingest.

Standard library only — no dependencies.

Script

import csv
import json
import re
from pathlib import Path


def apply_transform(value, transform):
    if value is None or value == "":
        return None
    if transform == "parse_float":
        cleaned = re.sub(r"[^0-9.\-]", "", str(value))
        try:
            return float(cleaned)
        except ValueError:
            return None
    if transform == "trim":
        return str(value).strip()
    if transform == "uppercase":
        return str(value).upper()
    if transform == "lowercase":
        return str(value).lower()
    if transform == "strip_html":
        return re.sub(r"<[^>]*>", "", str(value))
    return value


def transform_row(row, mapping):
    out = {}
    for canonical_field, spec in mapping.items():
        if isinstance(spec, str):
            out[canonical_field] = row.get(spec)
        else:
            value = row.get(spec["source"])
            out[canonical_field] = apply_transform(value, spec.get("transform"))
    return out


def main():
    mapping_config = json.loads(Path("mapping.json").read_text())
    mapping = mapping_config["mapping"]

    with open("raw-products.csv", newline="", encoding="utf-8") as src:
        reader = csv.DictReader(src)
        canonical = [transform_row(row, mapping) for row in reader]

    payload = {"products": canonical}
    Path("products.json").write_text(json.dumps(payload))

    print(f"Wrote {len(canonical)} canonical products")


if __name__ == "__main__":
    main()

Output

products.json will contain a single JSON object, {"products": [...]}, ready to be POSTed to the push-ingest endpoint.

Rows that fail validation are rejected and do not count toward accepted_product_count — dry_run is not yet supported (planned).

Search API

Query response

POST /api/v0/product/search/queryresponse

Generates an LLM-driven natural-language recommendation for a shopper's query — the conversational text shown above product results. This endpoint does not return products; it returns a single recommendation string.

The theme extension calls this endpoint first, then calls /api/v0/product/search/text or /api/v0/product/search/textandcolor to fetch the actual matching products.

Results are cached per (user_profile_id, normalized_query[, color]) so repeat queries return the same recommendation instantly.

Headers

Request body

Response — 200 OK

{
  "results": {
    "recommendation": "Here are a few breezy linen shirts under $80 that should feel great all day."
  }
}

Example

curl -X POST \
  https://developer-search-devID.region.run.app/api/v0/product/search/queryresponse \
  -H "X-Merchant-ID: 12345" \
  -H "Content-Type: application/json" \
  -d '{
    "query_str": "comfortable linen shirt under $80",
    "user_name": "Alex",
    "current_hour": 14
  }'

const res = await fetch(
  'https://developer-search-devID.region.run.app/api/v0/product/search/queryresponse',
  {
    method: 'POST',
    headers: {
      'X-Merchant-ID': '12345',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query_str: 'comfortable linen shirt under $80',
      user_name: 'Alex',
    }),
  },
);
const data = await res.json();
console.log(data.results.recommendation);

import httpx

r = httpx.post(
    "https://developer-search-devID.region.run.app/api/v0/product/search/queryresponse",
    headers={"X-Merchant-ID": "12345", "Content-Type": "application/json"},
    json={"query_str": "comfortable linen shirt under $80", "user_name": "Alex"},
)
print(r.json()["results"]["recommendation"])

Errors

Text search

POST /api/v0/product/search/text

The workhorse search endpoint. Takes a natural-language query, runs a semantic-similarity search over the merchant's catalog, filters by price, and returns ranked products plus a conversational recommendation.

Supports natural-language price constraints in the query string — "linen shirt under $80", "dress between $50 and $120", "sneakers around $200" — which are parsed out and applied as numeric filters.

Results are cached for 7 days, keyed on the normalized query plus any relevant preference fields.

Headers

Request body

Response — 200 OK

{
  "results": {
    "data": [
      {
        "product_id": "SKU-1001",
        "product_name": "Relaxed-Fit Linen Button-Up",
        "handle": "relaxed-fit-linen-button-up",
        "brand": "Cove & Coast",
        "category": "tops",
        "price": "69.00",
        "price_numeric": 69.0,
        "image1": "https://cdn.example.com/images/relaxed-linen.jpg",
        "distance": 0.213
      }
    ]
  },
  "recommendation": "Here are a few breezy linen shirts under $80 that should feel great all day.",
  "success": true
}

distance is the similarity score between the query and the product's embedding — lower is better. Each product also carries every canonical products field that was populated for the row.

Example

curl -X POST \
  https://developer-search-devID.region.run.app/api/v0/product/search/text \
  -H "X-Merchant-ID: 12345" \
  -H "Content-Type: application/json" \
  -d '{
    "query_str": "comfortable linen shirt under $80",
    "limit": 10,
    "gender": ["mens", "unisex"]
  }'

const res = await fetch(
  'https://developer-search-devID.region.run.app/api/v0/product/search/text',
  {
    method: 'POST',
    headers: {
      'X-Merchant-ID': '12345',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query_str: 'comfortable linen shirt under $80',
      limit: 10,
    }),
  },
);
const data = await res.json();
console.log(`${data.results.data.length} products`);

import httpx

r = httpx.post(
    "https://developer-search-devID.region.run.app/api/v0/product/search/text",
    headers={"X-Merchant-ID": "12345", "Content-Type": "application/json"},
    json={"query_str": "comfortable linen shirt under $80", "limit": 10},
)
print(len(r.json()["results"]["data"]))

Errors

Text and color search

POST /api/v0/product/search/textandcolor

Runs a combined text and color search. Either query_str or color can be omitted individually, but at least one must be provided. The endpoint determines its operation_type automatically:

• Both text and color → textandcolor
• Color only → color
• Text only → text

Natural-language price constraints in query_str are parsed and applied, just like text search. Results are cached for 7 days on a normalized query|color cache key.

Headers

Request body

Response — 200 OK

{
  "results": {
    "data": [
      {
        "product_id": "SKU-2003",
        "product_name": "Navy Linen Blazer",
        "price": "189.00",
        "price_numeric": 189.0,
        "image1": "https://cdn.example.com/images/navy-blazer.jpg",
        "color": "navy blue",
        "distance": 0.187
      }
    ]
  },
  "recommendation": "These navy pieces should layer beautifully for a smart-casual look.",
  "success": true
}

Example

curl -X POST \
  https://developer-search-devID.region.run.app/api/v0/product/search/textandcolor \
  -H "X-Merchant-ID: 12345" \
  -H "Content-Type: application/json" \
  -d '{
    "query_str": "blazer for a wedding",
    "color": "navy",
    "limit": 8
  }'

const res = await fetch(
  'https://developer-search-devID.region.run.app/api/v0/product/search/textandcolor',
  {
    method: 'POST',
    headers: {
      'X-Merchant-ID': '12345',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query_str: 'blazer for a wedding',
      color: 'navy',
      limit: 8,
    }),
  },
);

import httpx

r = httpx.post(
    "https://developer-search-devID.region.run.app/api/v0/product/search/textandcolor",
    headers={"X-Merchant-ID": "12345", "Content-Type": "application/json"},
    json={"query_str": "blazer for a wedding", "color": "navy", "limit": 8},
)