# Novelkeys — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/novelkeys/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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.beta.paywithlocus.com/api/wrapped/credits/novelkeys/get-all-switches \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/novelkeys/get-collection-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/novelkeys/get-new-arrivals \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/novelkeys/get-preorder-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/novelkeys/get-switch-availability-status \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/novelkeys/get-switch-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/novelkeys/get-switch-variants \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/novelkeys/list-all-collections \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/novelkeys/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.