# Hvacdirect — 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.

> Search and browse HVAC equipment from HVACDirect's catalog, viewing detailed product specifications, pricing, images, and compatible accessories all in one place. Find exactly what you need by searching product names, model numbers, or browsing by category.

**Category:** E-commerce | **Website:** [hvacdirect.com/](https://hvacdirect.com/) | **Docs:** [parse.bot/marketplace/12c806fd-0d24-4678-a5b0-591f0dd5d8bc/hvacdirect-com-api](https://parse.bot/marketplace/12c806fd-0d24-4678-a5b0-591f0dd5d8bc/hvacdirect-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/hvacdirect/`
**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

### Browse category

Browse products within a specific category by URL slug. Returns paginated product listings parsed from the category page HTML. Use slugs from the get_categories endpoint subcategory URLs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Category URL slug without .html extension (e.g. 'air-conditioner-condensers', 'furnaces') |
| `page` | integer | No | Page number for pagination |

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

### Get categories

Retrieve the site's top-level category navigation structure including main categories and their subcategories with URLs. Useful for discovering valid category slugs to pass to browse_category.

**Estimated cost:** Metered

_No parameters required._

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

### Get product accessories

Get recommended accessories and related products for a specific item. Returns accessories found on the product page including cross-sell and upsell items.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full product URL or path |

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

### Get product details

Retrieve full details for a product including specifications, description, images, stock status, and pricing. This is the canonical point-lookup for a single product by its URL.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full product URL or path (e.g. 'https://hvacdirect.com/aciq-12-000-btu-ptac-heat-pump-air-conditioner-unit-with-3-5kw-electric-heater.html') |

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

### Get product images

Get all available images for a product. Returns an object containing an array of image URLs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full product URL or path |

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

### Get product pricing

Get the current and original pricing for a product along with its SKU. Lightweight alternative to get_product_details when only price information is needed.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full product URL or path |

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

### Get product specifications

Retrieve technical specifications for a product as key-value pairs wrapped in a specifications object.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full product URL or path |

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

### Search by model number

Search for a product by its model number or SKU. Returns exact matches from the autocomplete API, falling back to full text search when no autocomplete results are found.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Model number or SKU to search for (e.g. 'STN855W', 'TH6320WF2003') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/hvacdirect/search-by-model-number \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### Search products

Full-text search over the product catalog via FastSimon. Returns matching products sorted by relevance or price. For common search terms that map to categories, results come from the autocomplete API with a category_url field. All results are returned in a single page; upstream does not reliably support multi-page traversal.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword (e.g. 'thermostat wifi', 'heat pump') |
| `sort` | string | No | Sort order for results. |

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