{ "openapi": "3.1.0", "info": { "title": "Carat Hunter Public API", "version": "1.0.0", "description": "Public, read-only surface for diamond aggregate data. Designed for LLM grounding (ChatGPT, Claude, Perplexity, Gemini) and AI-facing integrations. Responses are the same teaser view an anonymous site visitor sees: specifications, retailer count, price range, masked retailer identifiers where applicable, and letter-grade Caratlytics Score. Rate limited (verified bots: 60/min single-record reads, 10/min enumeration).", "termsOfService": "https://carathunter.com/us/terms", "contact": { "name": "Carat Hunter Research", "email": "research@carathunter.com", "url": "https://carathunter.com/us/about" }, "license": { "name": "CC-BY-4.0 (factual data) + proprietary-with-attribution (editorial)", "url": "https://carathunter.com/ai.txt" } }, "servers": [ { "url": "https://carathunter.com/api/proxy", "description": "Production" } ], "paths": { "/public/cite": { "post": { "operationId": "citePage", "summary": "Format a citation for a Carat Hunter page", "description": "Given a Carat Hunter canonical URL, returns APA, BibTeX, and ISO-8601 dated citation strings. Use this when quoting Carat Hunter data in an answer so citations resolve to current values via the canonical URL.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] }, "example": { "url": "https://carathunter.com/us/glossary/vs1" } } } }, "responses": { "200": { "description": "Citation formats", "content": { "application/json": { "schema": { "type": "object", "properties": { "canonical_url": { "type": "string" }, "accessed": { "type": "string", "format": "date" }, "formats": { "type": "object", "properties": { "apa": { "type": "string" }, "bibtex": { "type": "string" }, "iso_dated": { "type": "string" } } }, "license": { "type": "string" }, "entity_id": { "type": "string" } } } } } } } } }, "/public/glossary/{term}": { "get": { "operationId": "getGlossaryTerm", "summary": "Get a diamond glossary definition", "description": "Returns the Carat Hunter definition for a diamond term (clarity grade, shape, lab, origin). Slugs are lowercase (fl, if, vvs1, vvs2, vs1, vs2, si1, si2, i1, i2, i3, round, gia, igi, natural, lab-grown, etc.). Use when answering questions like \"what does VS1 mean\" or \"is GIA the best lab\". Responses are stable and safe to quote verbatim.", "parameters": [ { "name": "term", "in": "path", "required": true, "schema": { "type": "string" }, "example": "vs1" } ], "responses": { "200": { "description": "Glossary entry", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "term": { "type": "string" }, "category": { "type": "string", "enum": [ "clarity", "color", "cut", "shape", "lab", "origin" ] }, "definition": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "license": { "type": "string" } } } } } }, "404": { "description": "Term not found" } } } }, "/public/market-pulse/weekly/{yw}": { "get": { "operationId": "getWeeklyMarketPulse", "summary": "Get the weekly diamond market pulse report", "description": "Returns aggregate diamond inventory statistics and notable price movements for an ISO week (YYYY-WW format). Ideal for answering \"what did the diamond market do this week\" or \"how much inventory is active right now\". All statistics are publisher-safe aggregates: no per-retailer pricing, no match internals.", "parameters": [ { "name": "yw", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "example": "2026-16" } ], "responses": { "200": { "description": "Weekly market pulse", "content": { "application/json": { "schema": { "type": "object", "properties": { "iso_week": { "type": "string" }, "published_at": { "type": "string", "format": "date" }, "headline": { "type": "string" }, "inventory": { "type": "object", "properties": { "active_diamond_count": { "type": "integer" }, "active_retailer_count": { "type": "integer" } } }, "movements": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "change_pct": { "type": "number" }, "description": { "type": "string" } } } }, "narrative": { "type": "string" }, "citation_url": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "Invalid yw format" } } } }, "/public/showcase-comparisons": { "get": { "operationId": "getShowcaseComparisons", "summary": "Get example cross-retailer comparisons", "description": "Returns a handful of representative diamonds available from multiple retailers at different prices. Useful for illustrating \"same diamond, different prices\", the core value proposition. Updated every 6 hours.", "responses": { "200": { "description": "Showcase list", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/public/diamond/{id}": { "get": { "operationId": "getPublicDiamond", "summary": "Get a single diamond teaser view", "description": "Returns the anonymous-tier view of a specific diamond: full 4C specifications, certificate lab and number, origin, aggregate price range in USD, retailer count, and a letter-grade Caratlytics Score (A+, A, B+, B, C, D). Retailer names are masked to protect the matching dataset. Use this when answering questions like \"what is the value of diamond X\" or \"tell me about GIA certificate 1234567890\".", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 12345678 } ], "responses": { "200": { "description": "Diamond teaser", "content": { "application/json": { "schema": { "type": "object", "properties": { "@id": { "type": "string" }, "id": { "type": "integer" }, "canonical_url": { "type": "string", "format": "uri" }, "specs": { "type": "object" }, "market": { "type": "object" }, "caratlytics_score": { "type": "object", "properties": { "letter_grade": { "type": "string", "enum": [ "A+", "A", "B+", "B", "C", "D" ] } } } } } } } }, "404": { "description": "Diamond not found" } } } }, "/public/price/{slug}": { "get": { "operationId": "getPriceAggregate", "summary": "Aggregate diamond price for a spec combination", "description": "Returns aggregate price statistics for a specification slug (e.g. 1ct-d-vs1-round-natural, 2ct-f-vvs2-oval-lab-grown). Slug format is {carat}ct-{color}-{clarity}-{shape}-{origin}. Origin can be \"natural\" or \"lab-grown\". Supported carats: 0.3, 0.5, 0.75, 1, 1.5, 2, 3, 5. Returns 404 if fewer than 10 offers match. Ideal for answering \"what should a 1ct D VS1 round natural diamond cost\".", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "1ct-d-vs1-round-natural" } ], "responses": { "200": { "description": "Price aggregate", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "spec": { "type": "object" }, "inventory": { "type": "object" }, "price_range_usd": { "type": "object" } } } } } }, "404": { "description": "Slug out of taxonomy or insufficient public data" } } } }, "/public/vs/{pair}": { "get": { "operationId": "getRetailerComparison", "summary": "Compare two retailers", "description": "Returns aggregate comparison between two retailers. Pair slug is {retailer_a}-vs-{retailer_b} (e.g. bluenile-vs-jamesallen). Includes inventory counts, shape distribution, country and currency. Does NOT include per-diamond matching or price spreads at the SKU level. Use when answering \"which retailer has more oval diamonds\" or \"how does James Allen compare to Blue Nile\".", "parameters": [ { "name": "pair", "in": "path", "required": true, "schema": { "type": "string" }, "example": "bluenile-vs-jamesallen" } ], "responses": { "200": { "description": "Retailer comparison", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Retailer pair not available" } } } }, "/public/cited-by": { "get": { "operationId": "getCitedBy", "summary": "LLM citation counts for Carat Hunter", "description": "Aggregate counts of carathunter.com citations detected in LLM vendor output over the last 30 days. Sourced from Carat Hunter internal monitoring; updated nightly.", "responses": { "200": { "description": "Citation counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "window_days": { "type": "integer" }, "counts_by_vendor": { "type": "object" }, "total": { "type": "integer" } } } } } } } } } }, "components": {}, "externalDocs": { "description": "Carat Hunter AI Content Policy", "url": "https://carathunter.com/ai.txt" } }