--- title: "Get Variety Page" method: GET path: "/api/v1/market/v2/variety/{variety}" tags: ["Market V2"] --- # Get Variety Page `GET /api/v1/market/v2/variety/{variety}` ## Request - Base URL: `https://api.gemstoneaiapp.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.gemstoneaiapp.com/api/v1/market/v2/variety/{variety}` - Auth: none declared GET /api/v1/market/v2/variety/{variety} Full variety-page payload: index block + honest history_periods, signal breakdown, pricing ladder, comps preview (8 newest with image), news (variety-tagged, padded with general items flagged is_family_level), species content / supply / market data (null when unpopulated), and the caller's position in this variety. 404 for varieties the index doesn't track. ## Path parameters - `variety` string, required ## Headers - `X-Device-Id` integer, nullable - `authorization` string, nullable ## Response `200` Successful Response - VarietyPageResponse - `index_method` string - `verified_listing_count` integer, nullable - `variety` string, required - `tier` string - `image_url` string, nullable - `index` VarietyIndexBlock, required - `index_value` number, required - `change_1d_pct` number, nullable - `change_7d_pct` number, nullable - `change_30d_pct` number, nullable - `change_1y_pct` number, nullable - `confidence_tier` string - `explanation_headline` string, nullable - `as_of` string, required - `mark` MarkBlock: THE MARK: our measurement, struck monthly. Distinct from `asks`, which is what sellers are currently listing. Both are true and mean different things. `bands` is empty when no cell cleared the gates. The client shows the curated reference price in that case, labelled as such, and never a mark. - `bands` MarkBand[] - `size_band` string, required - `label` string, required - `ppc_p25` number, required - `ppc_p50` number, required - `ppc_p75` number, required - `n` integer, required - `sources` integer, required - `mom_pct` number, nullable - `measured_month` string, nullable - `next_strike` string, nullable - `asks` AsksBlock: What is listed RIGHT NOW. An observation, not a price claim. Unbanded and ungated on purpose: its honesty comes from being labelled asks. - `count` integer, required - `median` number, required - `p25` number, required - `p75` number, required - `observed_through` string, nullable - `history_periods` string[] - `signals` IndexMoversResponse, required - `variety` string, required - `change_pct` number, nullable - `explanation_headline` string, nullable - `movers` IndexMover[] - `signal` string, required - `label` string, required - `value` number, required - `direction` string, required - `signal_breakdown` object - `ladder` LadderBand[] - `size_band` string, required - `label` string, required - `n_comps` integer, required - `ppc_p25` number, required - `ppc_p50` number, required - `ppc_p75` number, required - `comps` CompsBlock - `total` integer - `items` CompListing[] - `id` integer, required - `gemstone_type` string, required - `carat_weight` number, nullable - `price_usd` number, nullable - `price_per_carat` number, nullable - `color` string, nullable - `color_grade` string, nullable - `clarity` string, nullable - `clarity_grade` string, nullable - `cut` string, nullable - `cut_grade` string, nullable - `shape` string, nullable - `origin` string, nullable - `origin_grade` string, nullable - `treatment` string, nullable - `treatment_grade` string, nullable - `category` string, nullable - `image_url` string, required - `source_name` string, required - `source_url` string, nullable - `source_site` string, nullable - `observation_date` string, nullable - `news` NewsItemV2[] - `id` integer, required - `title` string, required - `url` string, nullable - `source_name` string, required - `published_at` string, date-time, required - `category` string, nullable - `sentiment_score` number, nullable - `impact_direction` string, nullable - `estimated_price_impact_pct` number, nullable - `user_facing_summary` string, nullable - `affected_species` string[], nullable - `affected_families` string[], nullable - `affected_countries` string[], nullable - `event_type` string, nullable - `severity` integer, nullable - `image_url` string, nullable - `ai_generated` boolean - `is_family_level` boolean - `outlet_count` integer - `species_content` SpeciesContentResponse - `history_lore` string, nullable - `cultural_significance` string, nullable - `geology_paragraph` string, nullable - `famous_stones` object[], nullable - `buyers_guide` string, nullable - `synthetic_species` string[], nullable - `simulants` string[], nullable - `common_treatments` object, nullable - `origin_subregions` object, nullable - `species` string, required: Species name, e.g. 'Emerald' - `content_version` integer, required - `updated_at` string, date-time, required - `supply` SupplyBlock - `variety` string, required - `top_origins` unknown[] - unknown - `supply_concentration_score` number, required - `annual_production_tonnes` number, nullable - `supply_risk_notes` string, nullable - `updated_at` string, date-time, nullable - `market_data` GemstoneMarketDetailResponse - `id` integer, required - `variety` string, required - `primary_source` string, nullable - `characteristics` string, nullable - `image_url` string, nullable - `value_drivers` object: Value drivers for carat, color, clarity, and cut - `market_dynamics` MarketDynamics, required - `supply_description` string, nullable - `total_global_supply` string, nullable - `in_circulation` string, nullable - `demand` string, nullable - `recent_trends` string, nullable - `market_insights` string[]: List of market insight facts - `pricing_2025` PricingDetails, required - `min` number, nullable - `avg` number, nullable - `max` number, nullable - `yoy_change_percent` number, nullable - `p10` number, nullable - `p25` number, nullable - `p50` number, nullable - `p75` number, nullable - `p90` number, nullable - `p95` number, nullable - `median_k` number, nullable: Median price in $K (p50 / 1000) - `computed_yoy_percent` number, nullable: Computed YoY % change vs. 2024 avg - `floor_k` number, nullable: Floor price in $K (min or p10 / 1000) - `premium_k` number, nullable: Premium price in $K (p75 / 1000) - `distribution_params` object, nullable: Params for bell curve: mean ($K), std ($K), skew hint - `historical_pricing` HistoricalPricing[]: Historical pricing from 2020-2024 - `year` integer, required - `avg_price` number, nullable - `event_note` string, nullable - `price_k` number, nullable: Avg price in $K for graph y-axis - `created_at` string, date-time, required - `updated_at` string, date-time, required - `distributions` DistributionsBlock: Specimen attribute breakdowns for a variety, computed from the comp corpus (price_observations, user scans fenced out). Each axis is the top values by listing count; empty axes are omitted by the client. - `total` integer - `colors` DistributionItem[] - `name` string, required - `count` integer, required - `shapes` DistributionItem[] - `name` string, required - `count` integer, required - `clarities` DistributionItem[] - `name` string, required - `count` integer, required - `treatments` DistributionItem[] - `name` string, required - `count` integer, required - `your_position` YourPosition - `owned_count` integer, required - `est_value` number, required - `gems` PositionGem[] - `id` integer, required - `name` string, required - `image_url` string, nullable - `estimated_value` number, nullable ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api.md) · [All operations](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api/revisions/fcb441f55161?raw)