Create dataset

post/v1/datasets

Creates an empty dataset in draft status and returns its id. A dataset is the container everything else hangs off: items are uploaded into it, data sources fill it, and search and chat run against it once it is active.

Required configuration

config must carry all six store fields — storeUrl, storeId, storeDomain, storeName, currency and countryCode. Each is validated in the order the keys appear in your JSON, then the six required keys are checked for presence. Any key outside the allowed set is rejected.

Good to know

The new dataset is draft. Call Activate dataset once it holds items to make it visible to search, chat and the widget.
name is trimmed before it is stored. description defaults to an empty string.
storeUrl may be sent with or without a scheme (example.com or https://example.com); it is stored exactly as sent.
currency and countryCode are validated case-insensitively but stored exactly as sent, so send them in upper case (USD, US).
countryCode is validated on create but is not persisted on the dataset and does not appear in later reads.
The response is 200 with just the datasetId; it does not echo the record. Follow up with Retrieve dataset if you need it.

Private keyapi.v1.datasets.createNo demo

Request body

application/jsonrequired

namestringrequired

Display name. Must be non-empty after trimming.

e.g. "Spring 2026"

descriptionstring

Free-text description.

default: ""e.g. "Women's spring drop"

autoPublishboolean

Whether newly processed items go live automatically. Anything other than an explicit false is treated as true.

default: true

objectrequired

Store details. All six of storeUrl, storeId, storeDomain, storeName, currency and countryCode are required; targetGender is optional. No other keys are accepted.

storeUrlstringrequired

The storefront URL, with or without a scheme. Must have a hostname containing a dot; localhost is rejected.

e.g. "https://example-boutique.com"

storeIdstringrequired

Your identifier for the store. Non-empty.

e.g. "58712345678"

storeDomainstringrequired

Bare domain of the store, for example shop.example.com.

e.g. "example-boutique.com"

storeNamestringrequired

Display name of the store. Non-empty.

e.g. "Example Boutique"

currencystringrequired

Three-letter ISO 4217 code. Send it in upper case; it is stored exactly as sent.

e.g. "USD"

countryCodestringrequired

Two-letter ISO 3166-1 alpha-2 code. Required and validated, but not stored on the dataset.

e.g. "US"

targetGenderstringnullable

Force every item in this dataset to one gender. Omit or send null to keep per-item detection.

One ofmenswomens

e.g. "womens"

Response

200The dataset was created.

datasetIdstring (uuid)required

Id of the new dataset. Use it as the datasetId path parameter everywhere else.

Errors

Every error is JSON with a single error string unless noted. Match on the status code; the message is for humans.

400

Request body must be valid JSON.

The request body could not be parsed as JSON.

400

Request body must be a JSON object.

The body is empty, or is valid JSON but not an object (for example an array, a string or null).

401

Organization not found. Please check the organizationId.

The organization that owns the key no longer exists. Checked after the body is validated.

422

Dataset name is required.

name is missing, not a string, or blank after trimming.

422

config must be an object.

config is null, an array or a primitive.

422

Unrecognized key "<key>" in config.

config contains a key other than storeUrl, storeId, storeDomain, storeName, currency, countryCode or targetGender.

422

Store URL is required.

config.storeUrl is present but empty or not a string.

422

Invalid hostname. Please provide a valid domain name

config.storeUrl has no hostname or points at localhost.

422

Invalid domain. Please provide a complete domain (e.g., example.com)

config.storeUrl's hostname has no dot (for example a bare word).

422

Invalid URL format. Please provide a valid URL (e.g., example.com or https://example.com)

config.storeUrl cannot be parsed as a URL even after https:// is prepended.

422

Store ID is required.

config.storeId is present but empty or not a string.

422

Store domain is required.

config.storeDomain is present but empty or not a string.

422

Store domain must be a valid domain (e.g., stylor.com or shop.example.com)

config.storeDomain is not a bare domain — no scheme, no path, and a TLD of at least two letters.

422

Store name is required.

config.storeName is present but empty or not a string.

422

Currency is required.

config.currency is present but empty or not a string.

422

Currency must be a valid 3-letter ISO currency code (e.g., USD, CAD, EUR)

config.currency is not three letters.

422

Country code is required.

config.countryCode is present but empty or not a string.

422

Country code must be a valid 2-letter ISO country code (e.g., US, CA, GB)

config.countryCode is not two letters.

422

Target gender must be 'mens', 'womens', or null.

config.targetGender is set to anything other than mens, womens or null.

422

Missing key "<key>" in config.

One of the six required config keys is absent. They are checked in the order storeUrl, storeId, storeDomain, storeName, currency, countryCode and the first missing one is reported.

curl -X POST "https://stylor.ai/api/v1/datasets" \
  -H "Authorization: Bearer $STYLOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Spring 2026",
  "description": "Women'\''s spring drop",
  "config": {
    "storeUrl": "https://example-boutique.com",
    "storeId": "58712345678",
    "storeDomain": "example-boutique.com",
    "storeName": "Example Boutique",
    "currency": "USD",
    "countryCode": "US",
    "targetGender": "womens"
  }
}'

Response · 200

{
  "datasetId": "c9b3c6c0-9b0f-4f42-bf3f-2b7a6b1b9d31"
}