# Introduction

> **Note:** the Chat and Outfit endpoints have been retired and now answer `410 Gone`. Use the v2 agent API's [Chat](https://stylor.ai/guides/rest/v2/agent-chat.md) and [Looks](https://stylor.ai/guides/rest/v2/generate-look.md) 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](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"
```

### 4. Run a search

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](https://stylor.ai/guides/rest/v1/searchItems.md) for the details, and [Prices in the shopper's country](https://stylor.ai/guides/rest/v2/markets.md) for how price lists, sales and fallbacks work.

## Next steps

- [Authentication](authentication): public versus private keys and how to manage them.
- [Errors](errors): the error format and how to handle it.
- [Rate limits and quotas](rate-limits): how usage is metered.
- [Streaming](streaming): real-time stylist replies over Server-Sent Events.
- [Pagination](pagination): how to page through list endpoints.
- [Demo mode](demo-mode): try the shopper-facing endpoints without your own data.