StylorDocs

Introduction

Note: the Chat and Outfit endpoints have been retired and now answer 410 Gone. Use the v2 agent API's Chat and Looks instead. The rest of v1 is unchanged.

The Stylor REST API lets you load a clothing catalogue, keep it in sync with your store, search it semantically, and run an AI stylist that turns a shopper's question into a complete outfit built from your own products.

Everything the dashboard does with a catalogue is available here, so you can automate ingest from your backend and build shopper-facing experiences on your storefront.

Base URL

All endpoints live under one base URL:

text
https://stylor.ai/api

Endpoint paths in this reference include the version, so a full URL looks like https://stylor.ai/api/v1/search. Requests and responses use JSON unless an endpoint says otherwise. File uploads use multipart/form-data, and the streaming endpoints return text/event-stream.

Authentication at a glance

Every metered request carries an organization API key as a Bearer token:

http
Authorization: Bearer $STYLOR_API_KEY

There are two kinds of key. Public keys (sgpt-pk-…) are safe in browser code and reach shopper-facing endpoints such as search and chat. Private keys (sgpt-sk-…::…) stay on your server and manage datasets, items, sources and uploads. See Authentication for which endpoint needs which key.

Core objects

Object What it is
Dataset A container for one catalogue. Everything else hangs off a dataset. It starts as draft and must be active before search and chat use it.
Data source A connection that fills a dataset from a store. Today the supported type is shopify-api.
Sync job One run of a data source. It fetches the store's catalogue and queues new, changed and removed products.
Queue entry A product waiting to be processed. Each uploaded or synced product becomes a queue entry first.
Item A processed product: your merchant data plus AI-extracted style metadata and stored images. Items are what search returns.
Chat A conversation with the stylist. Each reply contains slots, one per garment to find.

How the objects relate

Products flow through the API in one direction:

text
Dataset
  └─ Data source ──> Sync job ──> Queue entries ──> Items ──> Search / Chat
                                        ^
            Direct upload ──────────────┘
  1. You create a dataset for a store.
  2. You attach a data source and run a sync job, or upload products directly.
  3. Each product lands in the dataset's ingest queue, and a background worker turns it into an item. This step is asynchronous and can take a while for large catalogues.
  4. Once the dataset is active, its active items are searchable and available to the stylist.

Chat and search work together. Send the stylist a message and it replies with a plan of slots. For each search slot, call Search with the chatId and the slot's id to fill it with products.

Quickstart

This walkthrough takes a Shopify store from nothing to a first search result. Steps 1 to 3 use a private key and step 4 uses a public key.

1. Create a dataset

bash
curl -X POST https://stylor.ai/api/v1/datasets \
  -H "Authorization: Bearer $STYLOR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring 2026",
    "config": {
      "storeUrl": "https://example-boutique.com",
      "storeId": "58712345678",
      "storeDomain": "example-boutique.com",
      "storeName": "Example Boutique",
      "currency": "USD",
      "countryCode": "US"
    }
  }'
json
{ "datasetId": "c9b3c6c0-9b0f-4f42-bf3f-2b7a6b1b9d31" }

2. Connect the store and start a sync

Create a data source. A syncPeriod of 0 turns off automatic syncing so you control when it runs.

bash
curl -X POST https://stylor.ai/api/v1/datasets/$DATASET_ID/sources \
  -H "Authorization: Bearer $STYLOR_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "shopify-api",
    "endpoint": "https://example-store.myshopify.com/products.json",
    "syncPeriod": 0,
    "status": "active"
  }'

Creating a source does not start a sync. Queue one with the returned sourceId:

bash
curl -X POST https://stylor.ai/api/v1/datasets/$DATASET_ID/sources/$SOURCE_ID/sync/jobs \
  -H "Authorization: Bearer $STYLOR_PRIVATE_KEY"

Poll the job until status is completed, then watch the queue with GET /v1/datasets/{datasetId}/items/queue until its entries are processed. If you would rather not connect a store, send products straight to POST /v1/datasets/{datasetId}/items/upload.

3. Activate the dataset

A new dataset is a draft. Activate it so search and chat include it:

bash
curl -X PATCH https://stylor.ai/api/v1/datasets/$DATASET_ID/activate \
  -H "Authorization: Bearer $STYLOR_PRIVATE_KEY"

Search takes a public key, so this same call can run in the browser:

bash
curl -X POST https://stylor.ai/api/v1/search \
  -H "Authorization: Bearer $STYLOR_PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "relaxed linen shirt for a summer wedding",
    "filters": { "gender": "mens", "color_family": ["white", "beige"] },
    "limit": 5
  }'

The response contains results, best match first. Each result has its full product record and a scoring breakdown.

If the store sells in several countries, add the shopper's country (on a Shopify storefront, Shopify.country) and results are priced in their market, with products not sold there left out. See Search for the details, and Prices in the shopper's country for how price lists, sales and fallbacks work.

Next steps