# Mechanicalkeyboards — 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 compare mechanical keyboard switches, keyboards, keycaps, and parts with detailed specs, pricing, and customer reviews. Search products by brand, filter by availability, and read detailed reviews to find the perfect components for your custom keyboard setup.

**Category:** E-commerce | **Website:** [mechanicalkeyboards.com/](https://mechanicalkeyboards.com/) | **Docs:** [parse.bot/marketplace/f9d09cba-7c1b-4d35-91b8-dfd1e0848192/mechanicalkeyboards-com-api](https://parse.bot/marketplace/f9d09cba-7c1b-4d35-91b8-dfd1e0848192/mechanicalkeyboards-com-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/mechanicalkeyboards/`
**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 keyboard detail

Retrieve full details for a mechanical keyboard including all variants with pricing and SKUs, image URLs, parsed specifications, HTML description, and tags. The handle slug identifies the product.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handle` | string | Yes | Keyboard product handle slug (e.g. ducky-origin-vintage). Obtainable from get_keyboards or search_products results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mechanicalkeyboards/get-keyboard-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"handle":"<string>"}'
```

### Get keyboard specs

Retrieve technical specifications and characteristics for a mechanical keyboard by its handle. Returns brand, model name, form factor/layout (e.g. Full-size, TKL, 75%), physical dimensions (length/width/height in mm, null when not provided by the site), weight (null when not provided), available switch options, and a full characteristics object with all site-listed attributes (keycap profile, key count, interface, layout, materials, compatibility, etc.). Requires two HTTP requests per call: one for product data and one for the characteristics page. An optional brand parameter is accepted but does not filter the response (the product is identified by handle).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `brand` | string | No | Optional brand name for informational context (case-insensitive). Does not filter the result since the product is identified by handle. |
| `handle` | string | Yes | Keyboard product handle slug (e.g. ducky-origin-vintage). Obtainable from get_keyboards or search_products results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mechanicalkeyboards/get-keyboard-specs \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"brand":"<string>","handle":"<string>"}'
```

### Get keyboards

Retrieve a paginated list of mechanical keyboards from the mechanical-keyboards collection. Each page returns up to 30 products with name, brand, handle, price, availability, and thumbnail image. Optionally filter by brand name (case-insensitive match against vendor).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `brand` | string | No | Filter results by brand/vendor name (case-insensitive). Omitting returns all brands. |
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mechanicalkeyboards/get-keyboards \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"brand":"<string>","page":"<integer>"}'
```

### Get switch brands

Retrieve a list of all switch brands currently available in the keyboard-switches collection. The list is sorted alphabetically and reflects vendors of products on the first page of the collection.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mechanicalkeyboards/get-switch-brands \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get switch detail

Retrieve full details for a specific switch product including all variants with pricing and SKUs, image URLs, parsed specifications, feel type (linear/tactile/clicky), HTML description, and tags. The handle slug identifies the product.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handle` | string | Yes | Product handle slug (e.g. cherry-mx-red-45g-linear). Obtainable from get_switches or search_products results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mechanicalkeyboards/get-switch-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"handle":"<string>"}'
```

### Get switch reviews

Retrieve customer reviews and aggregate rating for a product by its handle. Returns individual reviews with author, rating, title, body, and date, plus an aggregate object with average rating and review count (may be null if no reviews widget is present).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `handle` | string | Yes | Product handle slug (e.g. cherry-mx-red-45g-linear). Obtainable from get_switches or search_products results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mechanicalkeyboards/get-switch-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"handle":"<string>"}'
```

### Get switches

Retrieve a paginated list of keyboard switches from the keyboard-switches collection. Each page returns up to 30 products with basic info, tags, and parsed specs (actuation force, pretravel, total travel). Use page parameter to advance through the catalog.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mechanicalkeyboards/get-switches \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### Search products

Search for products across the entire catalog by keyword. Returns matching products with name, handle, price, availability, image, URL path, and vendor. Results are limited by the limit parameter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return. |
| `query` | string | Yes | Search keyword (e.g. 'cherry', 'linear switch', 'gateron'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/mechanicalkeyboards/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","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.