Folksy APIfolksy.com ↗
Access Folksy product listings, shop data, categories, and sale items via API. Search by keyword, browse by category or subcategory, and retrieve full product details.
What is the Folksy API?
The Folksy API covers 6 endpoints for querying the UK's largest handmade craft marketplace, returning product listings, seller shop data, category and subcategory browsing, and full item details. The get_product_details endpoint exposes fields including materials, tags, seller stats, aggregate ratings, and schema.org-structured offer data. Whether you're building a price comparison tool or aggregating craft inventory, the API covers the core product surfaces of folksy.com.
curl -X GET 'https://api.parse.bot/scraper/6b4ed9d3-04cc-4898-8376-5d671e8f8117/search_products?query=silver+ring&page=1&sort_by=most_recent' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace folksy-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.folksy_api import Folksy, Product, ProductSummary, Section, Sort, Category
folksy = Folksy()
# Search for handmade silver rings sorted by lowest price
for item in folksy.marketplaces.search(query="silver ring", sort_by=Sort.PRICE_LOW, limit=5):
print(item.title, item.price, item.shop_title)
# Get full details for a search result
first_result = next(iter(folksy.marketplaces.search(query="necklace", limit=1)))
product = first_result.details()
print(product.name, product.offers.price_currency, product.offers.price)
# Browse jewellery category using the Section enum
jewellery = folksy.category(Section.JEWELLERY)
for product in jewellery.listings(limit=3):
print(product.name, product.brand.name, product.offers.availability)
# Browse rings subcategory
for ring in jewellery.subcategory_listings(subcategory="rings", limit=3):
print(ring.name, ring.category, ring.offers.price)
# Explore a specific shop
shop = folksy.shop("LuminosityArt")
for item in shop.listings(limit=3):
print(item.name, item.offers.price, item.brand.url)
# Browse sale items
for sale_item in folksy.marketplaces.sale_items(limit=3):
print(sale_item.name, sale_item.offers.price, sale_item.category)
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.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination |
| queryrequired | string | Search keyword or phrase |
| sort_by | string | Sort order for results |
| max_price | number | Maximum price filter in GBP |
| min_price | number | Minimum price filter in GBP |
{
"type": "object",
"fields": {
"items": "array of product summary objects with title, itemUrl, price, imageUrl, sectionName, description, id, shopUrl, shopTitle, sellerId",
"currentPage": "integer current page number",
"totalResults": "integer total number of matching results"
},
"sample": {
"data": {
"items": [
{
"id": 8598853,
"price": "30.00",
"title": "Green Tana Lawn Liberty Print Fabric Necklace",
"itemUrl": "https://folksy.com/items/8598853",
"shopUrl": "https://folksy.com/shops/SallyStone",
"imageUrl": "https://imagedelivery.net/example/public",
"sellerId": "SallyStone",
"sectionId": 26,
"shopTitle": "Hippystitch",
"description": "This handmade Liberty print fabric necklace...",
"sectionName": "Jewellery"
}
],
"currentPage": 1,
"totalResults": 796
},
"status": "success"
}
}About the Folksy API
Search and Browse
The search_products endpoint accepts a required query string and optional filters including min_price, max_price, and sort_by (accepted values: most_recent, price_low, price_high). Results are paginated via the page parameter and each item in the response includes title, price, imageUrl, description, shopTitle, shopUrl, sellerId, sectionName, and a direct itemUrl. The totalResults field lets you calculate pagination depth without guessing.
Category and Subcategory Listings
get_category_listings takes a category slug (e.g., jewellery, homeware, craft-supplies) and returns schema.org-structured Product objects with name, url, image, brand, category, description, and an offers block containing price, currency, and availability. get_subcategory_listings adds a required subcategory slug (e.g., rings, earrings, bracelets-bangles) under a parent category. Both endpoints paginate via page and return input_not_found if the slug doesn't exist.
Product Details and Shop Listings
get_product_details accepts a full Folksy product URL or a path starting with /items/ and returns the most granular data in the API: materials, tags, description, category, image, offers, seller_stats (items sold count), and aggregateRating with ratingValue, ratingCount, and reviewCount. These fields are returned when available on the listing. get_shop_listings takes a shop_name slug and returns all paginated products from that seller, including aggregateRating per item alongside the standard Product fields.
Sale Items
The get_sale_items endpoint requires no parameters beyond the optional page and returns all currently discounted products as schema.org Product objects with the same offer structure used across category endpoints.
The Folksy API is a managed, monitored endpoint for folksy.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when folksy.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official folksy.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track price changes across Folksy listings for handmade jewellery using
min_price/max_pricefilters insearch_products - Aggregate seller ratings and items-sold counts from
get_product_detailsto build a seller reputation index - Monitor a specific shop's inventory changes over time using
get_shop_listingswith paginated requests - Build a UK craft gift guide by browsing
get_category_listingsfor categories likecards-stationeryorhomeware - Extract materials data from
get_product_detailsto categorise handmade items by construction type - Surface currently discounted craft items via
get_sale_itemsfor a deal-tracking application - Populate a product comparison table using structured schema.org offer fields across search and category endpoints
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Folksy have an official developer API?+
What does `get_product_details` return beyond basic price and title?+
seller_stats object containing the items-sold count, and an aggregateRating block with ratingValue, ratingCount, and reviewCount. All of these are returned when present on the listing; sparse listings may omit some fields. The brand object links to the seller's shop URL.Does the API expose seller reviews or individual review text?+
ratingValue, ratingCount, reviewCount) via get_product_details and get_shop_listings, but individual review text and reviewer profiles are not included. You can fork this API on Parse and revise it to add an endpoint targeting individual product reviews.How does subcategory browsing handle invalid slugs?+
get_subcategory_listings returns an input_not_found response when the subcategory slug doesn't exist under the given parent category. Valid subcategory slugs include values like rings, earrings, bracelets-bangles, necklaces-pendants, and mens-jewellery under the jewellery parent category. Check the slug format matches the URL path on folksy.com before querying.Does the API cover Folksy seller profiles or shop statistics beyond item listings?+
get_product_details and get_shop_listings, but dedicated seller profile pages with biography, total sales figures, or follower counts are not covered. You can fork this API on Parse and revise it to add a shop profile endpoint.