# 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. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-folksy-com-api-7d036532/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## 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/parse-folksy-com-api-7d036532/get_category_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-folksy-com-api-7d036532/get_product_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-folksy-com-api-7d036532/get_sale_items \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-folksy-com-api-7d036532/get_shop_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-folksy-com-api-7d036532/get_subcategory_listings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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/parse-folksy-com-api-7d036532/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_price":"<number>","min_price":"<number>","page":"<integer>","query":"<string>","sort_by":"<string>"}'
```