## 1. Sign in and create an API key

Go to [/signin](/signin). Enter your email, enter the code that arrives,
done — no form, no approval wait. Then open [API keys](/app/keys), name a key
after whatever will use it, and create it.

**Copy the secret — it is shown exactly once.** After that no part of it is
shown again; the console lists the key by the name you gave it. The key
does not expire; revoke it when you're done with it.

Don't want an account yet? The [Explorer](/explorer) builds a request, shows
the live cURL for it, and renders an example response — all without signing
in. Signing in is only required when you want to run it against live data.

## 2. Make your first call

```bash
curl "https://api.stylumia.com/v1/sample?category=power_tools" \
  -H "Authorization: Bearer $STYLUMIA_KEY"
  # Never commit your key — see /docs/key-security
```

## 3. Read the response

```json
{
  "data": [
    {
      "product_id": "prd_5741354fa5d111f0a1ce7bcc",
      "sku": "1003097550",
      "url": "https://www.homedepot.com/p/1003097550",
      "domain": "homedepot.com",
      "retailer": "home_depot",
      "department": "tools",
      "category": "power_tools",
      "brand": "DEWALT",
      "model_number": "DCD771C2",
      "title": "20V MAX Cordless Drill/Driver Kit",
      "mrp": 179.0,
      "selling_price": 139.0,
      "discount_pct": 22.3,
      "currency": "USD",
      "color": "Yellow",
      "image_url": "https://images.example.com/1003097550.jpg",
      "crawl_date": "2026-06-14"
    }
  ],
  "pagination": { "next_cursor": null, "has_more": false },
  "meta": {
    "request_id": "req_4a1e9c2d6f8b3057a1c4",
    "resolved": { "retailer": null, "category": "power_tools", "department": null, "rcd": null, "start_date": null, "end_date": null },
    "coverage": { "combinations": 1, "matching_rows": 6, "corpus_rows": 2361, "earliest_date": "2026-06-14", "latest_date": "2026-08-14" }
  }
}
```

[`meta.resolved`](/docs/requests) echoes every filter the server actually
used, including the ones you didn't send. `meta.coverage` rides along on
every response, so one call tells you both what you got — 6 matching rows —
and how much exists in total — 2,361. `/v1/sample` has no `limit` parameter
and no cursor: it's capped at 100 rows, always, because a sample is for
judging shape, not for bulk reads.

## 4. Pull the full set — no discovery chain required

`retailer`, `category`, `department`, `rcd`, `start_date`, and `end_date` are
the same six optional filters on all three endpoints. There's no sequence to
walk — a filter you already know goes straight on the endpoint you want:

```bash
curl "https://api.stylumia.com/v1/catalog?category=power_tools&limit=50" \
  -H "Authorization: Bearer $STYLUMIA_KEY"
  # Never commit your key — see /docs/key-security
```

Know the retailer/category/department combination already? Send it as one
`rcd` triple instead of three parameters:

```bash
curl "https://api.stylumia.com/v1/catalog?rcd=home_depot:power_tools:tools" \
  -H "Authorization: Bearer $STYLUMIA_KEY"
  # Never commit your key — see /docs/key-security
```

Curious what exists before you pull it? [`GET /v1/coverage`](/docs/objects/reference-data)
answers that — but it's not a required first step. Every endpoint works
standalone.

```bash
curl "https://api.stylumia.com/v1/coverage?category=power_tools" \
  -H "Authorization: Bearer $STYLUMIA_KEY"
  # Never commit your key — see /docs/key-security
```

## 5. Break it on purpose

Guess a category instead of reading one from a coverage response:

```bash
curl "https://api.stylumia.com/v1/catalog?retailer=home_depot&category=power+tool" \
  -H "Authorization: Bearer $STYLUMIA_KEY"
  # Never commit your key — see /docs/key-security
```

```json
{
  "type": "https://developer-api.stylumia.net/errors#unknown_category",
  "title": "Unknown category",
  "status": 400,
  "detail": "'power tool' is not a recognized category for retailer 'home_depot'.",
  "code": "unknown_category",
  "retryable": false,
  "recovery": "Call GET /v1/coverage?retailer=... to list that retailer's categories, or use one of the suggestions in valid_options.",
  "field": "category",
  "valid_options": ["power_tools", "hand_tools", "tool_storage"],
  "request_id": "req_2c91af7d3e8016b4c9f0"
}
```

Rerun with the value it suggested:

```bash
curl "https://api.stylumia.com/v1/catalog?retailer=home_depot&category=power_tools" \
  -H "Authorization: Bearer $STYLUMIA_KEY"
  # Never commit your key — see /docs/key-security
```

200, real rows.

The error fixed your next call. That is the contract — it's also the only
vocabulary lookup this API has, now that there's no separate endpoint listing
retailers or categories on their own.

## Next steps

- [Authentication](/docs/authentication) — keys, rotation, the three easy 401s
- [Pagination](/docs/pagination) — walking `/v1/catalog` past the first page
- [API reference](/reference) — every endpoint
- [Error handling](/docs/error-handling) — the full contract behind that 400