StylorDocs

Update dataset

patch/v1/datasets/{datasetId}

Updates a dataset's name, description, metadata, status or store configuration. Send the changes inside a fields object; only the keys you include are touched.

Accepted fields

Field Rule
name Non-empty string. Trimmed, internal whitespace collapsed, cut to 200 characters.
description Any string (empty allowed). Whitespace collapsed, cut to 2000 characters.
metadata A plain JSON object. Replaces the whole metadata value; it is not merged.
status active, draft or archived.
config.storeDomain Bare domain, no scheme, path or query.
config.storeUrl http(s):// URL with a host — unlike create, the scheme is required here.
config.storeName Non-empty string, cut to 200 characters.
config.storeId Non-empty string, cut to 200 characters.
config.targetGender mens, womens or null.

Config fields can be sent nested ("config": { "storeUrl": … }) or as dot-path keys ("config.storeUrl": …).

Validation is all-or-nothing

Every field you send is checked before anything is written. If any field is invalid, or is not in the list above, nothing is changed and the response is 422 with a details array naming each failing field.

details[].path details[].message
fields No valid fields to update. Allowed fields: name, description, metadata, status, config.storeDomain, config.storeUrl, config.storeName, config.storeId, config.targetGender. (sent when fields is omitted or empty)
<key> or config.<key> Unsupported field: <key>
config config must be an object.
name name must be a non-empty string.
description description must be a string.
config.storeDomain config.storeDomain must be a valid domain excluding any path, query parameters, or HTTP method.
config.storeUrl config.storeUrl must be a valid http(s) URL.
config.storeName config.storeName must be a non-empty string.
config.storeId config.storeId must be a non-empty string.
config.targetGender config.targetGender must be 'mens', 'womens', or null.
status status must be 'active', 'draft', or 'archived'.
metadata metadata must be a plain object.

Good to know

  • Changing status here only flips the flag. Use Activate dataset and Archive dataset when you also want items, queue rows and data sources to follow, which is almost always.
  • Changing config.targetGender does not rewrite the gender already stored on existing items; only items ingested afterwards pick it up.
  • The response dataset is the full stored record, including organizationId and autoPublish, unlike Retrieve dataset.
Private keyapi.v1.datasets.updateNo demo

Path parameters

1
datasetIdstring (uuid)required

The dataset to update.

Request body

application/jsonrequired
objectrequired

The fields to change. Config values can be nested under config or sent as dot-path keys (config.storeUrl). Unrecognised keys are rejected with 422 and nothing is written.

namestring

New display name. Non-empty; whitespace collapsed; cut to 200 characters.

maxLength: 200
descriptionstring

New description. Empty string allowed; whitespace collapsed; cut to 2000 characters.

maxLength: 2000
metadataobject

Replaces the whole metadata object. Must be a plain object, not an array.

statusstring

Lifecycle state of a dataset. - draft — newly created; not visible to search, chat or the widget. - active — live. Any number of datasets can be active at once. - archived — parked. Data is kept, items and sources are switched off.

One ofdraftactivearchived
default: "draft"
object

Partial store configuration. Only the keys you send are changed.

Response

200The updated dataset.
Datasetrequired

The full stored dataset record. Returned by *Update dataset*, *Activate dataset* and *Archive dataset*. List and retrieve responses project a subset — see DatasetSummary and DatasetDetail. Internal _id and __v fields are stripped by *Update dataset* but are still present on the activate and archive responses; ignore them.

datasetIdstring (uuid)required

Unique id of the dataset. Use it as the datasetId path parameter.

e.g. "c9b3c6c0-9b0f-4f42-bf3f-2b7a6b1b9d31"
organizationIdstring (uuid)required

Id of the organization that owns the dataset — the one behind your API key.

e.g. "0a2c1f4e-5b6d-7e8f-9012-3456789abcde"
statusstringrequired

Lifecycle state of a dataset. - draft — newly created; not visible to search, chat or the widget. - active — live. Any number of datasets can be active at once. - archived — parked. Data is kept, items and sources are switched off.

One ofdraftactivearchived
default: "draft"
namestringrequired

Display name. Trimmed on create; cut to 200 characters on update.

e.g. "Spring 2026"
descriptionstring

Free-text description. Defaults to an empty string; cut to 2000 characters on update.

e.g. "Women's spring drop"
metadataobject

Arbitrary JSON you attach to the dataset. Omitted when never set. Replaced wholesale by *Update dataset*.

DatasetConfigrequired

Store details attached to a dataset. Set on create, editable field-by-field on update.

autoPublishbooleanrequired

Whether newly processed items go live automatically. Set on create; true unless explicitly false.

default: true
createdAtstring (date-time)required

When the dataset was created.

e.g. "2026-03-02T09:14:31.208Z"
updatedAtstring (date-time)required

When the dataset record was last written.

e.g. "2026-08-19T16:40:02.911Z"

Errors

25

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 for the provided organizationId.

The organization that owns the key no longer exists.

404
Dataset not found for this organization.

No dataset with that id belongs to your organization.

404
Update failed: dataset document not found or no changes applied.

The dataset disappeared between the ownership check and the write.

422
datasetId is required.

datasetId is empty or blank.

422
fields must be an object.

fields is null, an array, or a primitive.

422
Validation failed.

One or more fields failed validation, or fields was omitted or empty. Nothing was written. details has one { path, message } entry per failing field; the possible messages are listed in the description. The organization and dataset are checked first, so a 401 or 404 takes precedence.

{
  "error": "Validation failed.",
  "details": [
    {
      "path": "config.storeUrl",
      "message": "config.storeUrl must be a valid http(s) URL."
    },
    {
      "path": "colour",
      "message": "Unsupported field: colour"
    }
  ]
}
curl -X PATCH "https://stylor.ai/api/v1/datasets/YOUR_DATASET_ID" \
  -H "Authorization: Bearer $STYLOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": {
    "name": "Spring 2026 — final",
    "metadata": {
      "owner": "merchandising"
    }
  }
}'
Response · 200
{
  "dataset": {
    "datasetId": "c9b3c6c0-9b0f-4f42-bf3f-2b7a6b1b9d31",
    "organizationId": "0a2c1f4e-5b6d-7e8f-9012-3456789abcde",
    "status": "active",
    "name": "Spring 2026 — final",
    "description": "Women's spring drop",
    "metadata": {
      "owner": "merchandising"
    },
    "config": {
      "storeUrl": "https://example-boutique.com",
      "storeId": "58712345678",
      "storeDomain": "example-boutique.com",
      "storeName": "Example Boutique",
      "currency": "USD",
      "targetGender": "womens"
    },
    "autoPublish": true,
    "createdAt": "2026-03-02T09:14:31.208Z",
    "updatedAt": "2026-09-12T10:02:44.130Z"
  }
}