Retrieve a dataset item

get/v1/datasets/{datasetId}/items/{itemId}

Returns one processed item by its itemId. Unlike the list endpoint this returns the item whatever its status, so archived items can be read here.

The itemId is the id assigned when the product was uploaded to the queue; the queue entry and the processed item share it.

Private keyapi.v1.datasets.items.retrieveNo demo

Path parameters

datasetIdstring (uuid)required

The dataset's id, as returned when it was created.

itemIdstring (uuid)required

The item's itemId. It is the id the product's queue entry was given at upload.

Response

200The item.

DatasetItemrequired

A processed catalogue item. Items are created by the ingest pipeline from entries in the dataset's queue; you cannot write them directly. Vector embeddings are stored separately and are never returned. Image fields contain object keys, not URLs — see StoredImage for how to build a URL. Internal database identifiers and derived lookup keys are stripped from every response.

itemIdstring (uuid)required

Unique item id. It is the same id the queue entry was given at upload time.

e.g. "8b0a1b62-7c2a-4b7f-9e2c-0f3a9b1f0c11"

datasetIdstring (uuid)required

The dataset the item belongs to.

e.g. "c9b3c6c0-9b0f-4f42-bf3f-2b7a6b1b9d31"

organizationIdstring (uuid)required

The organization that owns the dataset.

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

statusstringrequired

Only active items are listed and searchable.

One ofactivearchived

e.g. "active"

versionnumberrequired

Ingest pipeline version the item was processed with.

e.g. 1

DatasetItemMetadatarequired

What Stylor's product labeller read from the item's photos and listing when it was processed. Fields with an enum are closed lists; the taxonomy (slot, family, features) is shared by every catalogue. Items processed before a field existed may lack it.

DatasetItemProductrequired

Merchant-facing product data. Everything here comes from your upload or your dataset configuration, not from AI.

DatasetItemOriginrequired

Where the item came from. Copied from the dataset's store configuration at processing time.

createdAtstring (date-time)required

When the processed item was first written.

e.g. "2025-03-04T18:22:41.913Z"

updatedAtstring (date-time)required

When the item was last rewritten by a sync or reprocess.

e.g. "2025-03-04T18:22:41.913Z"

Errors

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

401

Organization '<organizationId>' not found.

The organization encoded in the API key no longer exists.

404

Dataset not found for this organization.

No dataset with this datasetId belongs to the key's organization.

404

Item '<itemId>' not found in dataset '<datasetId>' for organization '<organizationId>'.

The dataset exists but holds no item with this itemId.

curl -X GET "https://stylor.ai/api/v1/datasets/YOUR_DATASET_ID/items/YOUR_ITEM_ID" \
  -H "Authorization: Bearer $STYLOR_API_KEY"

Response · 200

{
  "item": {
    "itemId": "8b0a1b62-7c2a-4b7f-9e2c-0f3a9b1f0c11",
    "datasetId": "c9b3c6c0-9b0f-4f42-bf3f-2b7a6b1b9d31",
    "organizationId": "0a2c1f4e-5b6d-7e8f-9012-3456789abcde",
    "status": "active",
    "version": 1,
    "metadata": {
      "description": "classic crew tee mens black relaxed t shirt cotton crew neck short sleeve",
      "gender": "mens",
      "age_group": "adult",
      "color_rgb": [
        28,
        28,
        30
      ],
      "color_family": "black",
      "colors": [
        "black"
      ],
      "pattern": "solid",
      "material": [
        "cotton"
      ],
      "fit": "relaxed",
      "slot": "top",
      "family": "t shirt",
      "features": [
        {
          "axis": "neckline",
          "value": "crew",
          "confidence": 0.97
        },
        {
          "axis": "sleeve",
          "value": "short",
          "confidence": 0.99
        }
      ],
      "featureKeys": [
        "neckline:crew",
        "sleeve:short"
      ],
      "taxonomyVersion": 4,
      "searchTextVersion": 2
    },
    "product": {
      "sku": "A1A2P-BB2J",
      "url": "https://shop.example.com/products/classic-crew-tee",
      "name": "Classic Crew Tee",
      "description": "<p>A heavyweight organic cotton tee with a relaxed fit.</p>",
      "careInstructions": "",
      "price": 49,
      "currency": "USD",
      "model": {
        "height": "",
        "size": ""
      },
      "setItems": [],
      "recommendedItems": [],
      "assets": {
        "images": [
          {
            "originalImageUrl": "https://cdn.shopify.com/s/files/1/0001/products/tee-front.jpg",
            "type": "",
            "uploaded": {
              "id": "3f9c2a1e-8d4b-4c6f-9a2e-1b7d5e0c4f88",
              "key": "images/3f9c2a1e-8d4b-4c6f-9a2e-1b7d5e0c4f88.jpeg"
            }
          }
        ],
        "generated": {
          "thumbnail": {
            "url": null
          },
          "segmented": []
        }
      },
      "variants": [
        {
          "variantId": "gid://shopify/ProductVariant/41611609636909",
          "sku": "A1A2P-BB2J-M",
          "label": "M / Black",
          "options": [
            {
              "name": "Size",
              "value": "M"
            },
            {
              "name": "Color",
              "value": "Black"
            }
          ],
          "inStock": true,
          "quantity": 4,
          "price": 49,
          "compareAtPrice": null
        }
      ]
    },
    "origin": {
      "siteUrl": "https://shop.example.com",
      "brandId": "shop-example",
      "brand": "Example Apparel",
      "country": "CA"
    },
    "createdAt": "2025-03-04T18:22:41.913Z",
    "updatedAt": "2025-03-04T18:22:41.913Z"
  }
}