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

> Search and browse handmade products on Folksy by category, subcategory, or shop, and access detailed product information including pricing and availability. Discover sales and special offers while exploring artisan shops and their complete listings.

**Category:** Marketplaces | **Website:** [folksy.com/](https://folksy.com/) | **Docs:** [parse.bot/marketplace/7d036532-1bae-4ed1-9e04-1bc62b71e322/folksy-com-api](https://parse.bot/marketplace/7d036532-1bae-4ed1-9e04-1bc62b71e322/folksy-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/folksy/`
**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 category listings

Browse products by top-level category. Returns product listings with structured schema.org Product data including name, price, image, brand, and availability. Results are paginated.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Category slug |
| `page` | integer | No | Page number for pagination |

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

### Get product details

Retrieve full details of a single product listing including description, materials, tags, seller stats, and aggregate rating. Extracts schema.org Product JSON-LD plus HTML-embedded metadata.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full product URL (e.g., https://folksy.com/items/8631985-textured-sterling-silver-wrap-ring) or path starting with / |

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

### Get sale items

Browse products currently on sale. Returns paginated product listings with structured schema.org Product data.

**Estimated cost:** Metered

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

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

### Get shop listings

Retrieve all product listings from a specific seller's shop. Returns paginated product data with structured schema.org Product objects including aggregate ratings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination |
| `shop_name` | string | Yes | Shop name/slug as it appears in the shop URL (e.g., LuminosityArt, ARCJewellery, emmafox) |

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

### Get subcategory listings

Browse products by subcategory within a parent category. Returns product listings with structured schema.org Product data. Returns input_not_found if the category/subcategory slug combination does not exist.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Parent category slug |
| `page` | integer | No | Page number for pagination |
| `subcategory` | string | Yes | Subcategory slug (e.g., rings, earrings, bracelets-bangles, brooches, necklaces-pendants, paintings, prints-digital-art) |

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

### Search products

Full-text search across all Folksy marketplace products. Returns paginated results with product title, price, description, shop info, and image URL. The search API uses Elasticsearch under the hood; query matches title and description. Sorting options control result order. Price filters narrow results to a GBP range. Each page returns up to ~48 items.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `max_price` | number | No | Maximum price filter in GBP |
| `min_price` | number | No | Minimum price filter in GBP |
| `page` | integer | No | Page number for pagination |
| `query` | string | Yes | Search keyword or phrase |
| `sort_by` | string | No | Sort order for results |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/folksy/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"max_price":"<number>","min_price":"<number>","page":"<integer>","query":"<string>","sort_by":"<string>"}'
```

## Next steps

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