Clean Origin APIcleanorigin.com ↗
Access Clean Origin's lab-grown diamond listings, engagement ring settings, jewelry categories, and customer reviews via 7 structured API endpoints.
What is the Clean Origin API?
The Clean Origin API exposes 7 endpoints for querying lab-grown diamonds, engagement ring settings, jewelry subcategories, and customer reviews from cleanorigin.com. The search_diamonds endpoint accepts filters for shape, carat range, color, clarity, cut, and price, returning up to 40 results per page with SKU, grading details, and pricing. Separate endpoints cover individual diamond detail pages, ring product specs, and Yotpo-sourced customer reviews.
curl -X GET 'https://api.parse.bot/scraper/5dec1c22-0722-4d0b-b8aa-5be0fed5e42d/search_diamonds?cut=Excellent&page=1&color=D&shape=Round&clarity=VS1&max_carat=3.0&max_price=5000&min_carat=1.0&min_price=100&creation_method=Lab' \ -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 cleanorigin-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.
"""Clean Origin: search diamonds, browse rings, and read reviews."""
from parse_apis.clean_origin_api import CleanOrigin, Shape, CutGrade, RingStyle, Sort, ItemNotFound
client = CleanOrigin()
# Search for round excellent diamonds under $2000
for diamond in client.diamonds.search(shape=Shape.ROUND, cut=CutGrade.EXCELLENT, max_price=2000, limit=3):
print(diamond.shape, diamond.carat, diamond.color, diamond.price)
# Drill into the first result for full details
summary = client.diamonds.search(shape=Shape.EMERALD, limit=1).first()
if summary:
detail = summary.details()
print(detail.title, detail.price, detail.carat, detail.cut)
# Search engagement rings sorted by price
for ring in client.products.search_rings(style=RingStyle.SOLITAIRE, sort=Sort.PRICE, limit=3):
print(ring.name, ring.price, ring.image)
# Get full product detail from a ring summary
ring_summary = client.products.search_rings(style=RingStyle.HALO, limit=1).first()
if ring_summary:
try:
product = ring_summary.details()
print(product.name, product.brand, product.specifications)
except ItemNotFound as exc:
print(f"Product not found: {exc.slug}")
# Browse site-wide reviews
for review in client.reviews.list(limit=3):
print(review.user, review.rating, review.title)
# List subcategories
for sub in client.subcategories.list_engagement_rings(limit=5):
print(sub.name, sub.url)
print("exercised: diamonds.search / details / products.search_rings / details / reviews.list / subcategories.list_engagement_rings")Search and filter lab-grown diamonds with support for shape, carat, price, color, clarity, and pagination. Returns up to 40 results per page. Server-side filtering covers shape, carat range, price range, color, clarity, cut grade, and creation method. Results are paginated; each DiamondSummary exposes a navigation op to fetch full Diamond details.
| Param | Type | Description |
|---|---|---|
| cut | string | Cut grade filter, comma-separated for multiple values |
| page | integer | Page number for pagination |
| color | string | Color grade filter, comma-separated for multiple values (e.g. D,E,F) |
| shape | string | Diamond shape filter |
| clarity | string | Clarity grade filter, comma-separated for multiple values (e.g. VS1,VS2,SI1) |
| max_carat | number | Maximum carat weight |
| max_price | number | Maximum price in USD |
| min_carat | number | Minimum carat weight |
| min_price | number | Minimum price in USD |
| creation_method | string | Filter by creation method: Lab or Natural. Omitting defaults to Lab. |
{
"type": "object",
"fields": {
"page": "integer current page number",
"diamonds": "array of diamond summary objects with sku, url, shape, carat, cut, color, clarity, price, original_price",
"total_count": "integer total matching diamonds"
},
"sample": {
"data": {
"page": 1,
"diamonds": [
{
"cut": "Excellent",
"sku": "1537410",
"url": "https://www.cleanorigin.com/diamonds/emerald-lab-grown-diamond-6baf1df6a645/",
"carat": "1.00",
"color": "D",
"price": "400",
"shape": "Emerald",
"clarity": "VS2",
"original_price": null
}
],
"total_count": 23564
},
"status": "success"
}
}About the Clean Origin API
Diamond Search and Detail
The search_diamonds endpoint accepts up to eight filter parameters: shape (Round, Oval, Cushion, and seven others), cut, color, clarity, min_carat, max_carat, max_price, and page. Each result in the diamonds array includes sku, url, shape, carat, cut, color, clarity, price, and original_price, making it straightforward to compare grading tiers or detect discounts. The total_count field lets you calculate page counts for full traversal. For a single stone, get_diamond_detail takes a URL slug and returns the same grading fields plus an images array.
Engagement Rings and Jewelry Products
search_engagement_rings filters settings by metal (e.g. 14K White Gold, 14K Rose Gold), style (Solitaire, Halo, Three Stone, Vintage, Classic), price range, and sort order. Each product object in the products array carries name, url, price, original_price, sku, image, and tags. get_product_detail accepts a slug that includes the category path (e.g. engagement/kendall-ring-ajr04662-e) and returns richer data: specifications as a key-value object, a description field, and a full images array. This same endpoint covers wedding rings and other jewelry items.
Subcategories and Reviews
get_engagement_ring_subcategories and get_jewelry_subcategories each return a flat list of name and url pairs — useful for building navigation or seeding batch product queries. The get_product_reviews endpoint queries Yotpo reviews. Pass a sku for product-level reviews or omit it for site-wide reviews; both paths support page and limit pagination. Each review object includes id, user, date, title, content, rating, and product.
The Clean Origin API is a managed, monitored endpoint for cleanorigin.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when cleanorigin.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 cleanorigin.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?+
- Build a diamond comparison tool filtering by cut, color, clarity, and carat range using
search_diamonds - Track price changes on specific lab-grown diamond SKUs over time using
get_diamond_detail - Populate an engagement ring configurator with setting options filtered by metal type and style
- Aggregate customer sentiment by pulling site-wide Yotpo reviews via
get_product_reviews - Generate a structured jewelry catalog by enumerating subcategories and fetching product specs with
get_product_detail - Identify discounted diamonds by comparing
priceagainstoriginal_priceacross paginated search results
| 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 Clean Origin have an official developer API?+
What grading fields does `search_diamonds` return for each diamond?+
search_diamonds returns shape, carat, cut, color, clarity, price, and original_price for each result, along with a sku and url. For images you need to call get_diamond_detail with the diamond's slug.Can I filter engagement rings by metal types other than 14K White Gold and 14K Rose Gold?+
search_engagement_rings endpoint currently documents 14K White Gold and 14K Rose Gold as accepted metal values. Other metal options (such as 18K or platinum) are not listed as supported filter values. You can fork this API on Parse and revise it to add any additional metal filter values if Clean Origin's catalog expands.Does the API expose ring sizing, stone pairing, or 360-degree video assets?+
get_product_detail returns images (an array of image URLs), specifications, description, price, and sku, but does not include ring size options, diamond pairing flows, or video assets. You can fork the API on Parse and revise it to add the missing endpoint if those fields become accessible.How does pagination work across the search endpoints?+
search_diamonds and search_engagement_rings return up to 40 results per page. The response includes a total_count field so you can compute how many pages exist and iterate using the page parameter. get_product_reviews supports both page and a limit parameter for finer control.