# Novelkeys — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Browse and search NovelKeys' complete catalog of mechanical keyboard products—including switches, keyboards, keycaps, and their availability status—to find exactly what you need. Check preorder options, discover new arrivals, and get detailed product information across all collections in one place.

**Category:** E-commerce | **Website:** [novelkeys.xyz/](https://novelkeys.xyz/) | **Docs:** [parse.bot/marketplace/e6055fce-4292-4942-beac-5195361e74d2/novelkeys-xyz-api](https://parse.bot/marketplace/e6055fce-4292-4942-beac-5195361e74d2/novelkeys-xyz-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-novelkeys-xyz-api-e6055fce/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_all_switches

Fetch all mechanical keyboard switch products from the switches collection. Returns the full list with pagination handled internally. Each product includes id, title, handle, variants, images, tags, vendor, and pricing.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-novelkeys-xyz-api-e6055fce/get_all_switches \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_collection_products

Fetch all products within a specific collection by its handle. Paginates internally to return the complete product list for that collection.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handle` | string | Yes | Collection handle (URL slug), e.g. 'keycaps', 'switches', 'keyboards' |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-novelkeys-xyz-api-e6055fce/get_collection_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handle":"<string>"}'
```

### get_new_arrivals

Fetch the most recently added or updated products from the site. Returns up to 50 products sorted by recency, including full variant and image data.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-novelkeys-xyz-api-e6055fce/get_new_arrivals \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_preorder_products

Fetch products that are currently available for preorder. Checks the preorders collection first, then falls back to filtering all products by preorder tags. Returns products with their full variant and image data.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-novelkeys-xyz-api-e6055fce/get_preorder_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_switch_availability_status

Determine the real-time availability status of a product and each of its variants. Returns variant-level stock status: IN STOCK, SOLD OUT, PREORDER, or CLEARANCE. Status is derived from product tags and variant availability flags.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handle` | string | Yes | Product handle (URL slug), e.g. 'cherry-switches' |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-novelkeys-xyz-api-e6055fce/get_switch_availability_status \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handle":"<string>"}'
```

### get_switch_details

Fetch full details for a specific product by its URL handle. Returns complete product data including all variants, images, options, and metadata. Use any product handle from search or collection listings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handle` | string | Yes | Product handle (URL slug), e.g. 'cherry-switches', 'typeplus-peacock-switches' |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-novelkeys-xyz-api-e6055fce/get_switch_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handle":"<string>"}'
```

### get_switch_variants

Extract all variants (sub-types) for a given product. Returns variant details including title, price, SKU, and availability for each option.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handle` | string | Yes | Product handle (URL slug), e.g. 'cherry-switches' |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-novelkeys-xyz-api-e6055fce/get_switch_variants \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"handle":"<string>"}'
```

### list_all_collections

Retrieve all available product collections on the site. Paginates internally to return the complete list. Each collection includes title, handle, description, and product count.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-novelkeys-xyz-api-e6055fce/list_all_collections \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_products

Search across all products on the site using keyword matching. Returns matching products with summary information including price range and availability. Covers all product types: switches, keycaps, keyboards, accessories.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword, e.g. 'cherry', 'gateron', 'keycaps' |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-novelkeys-xyz-api-e6055fce/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```