{"openapi":"3.1.0","info":{"title":"Swanum Comps API","description":"Sold prices from resale marketplaces (Vinted now, eBay being measured) in one consistent JSON shape.","version":"1.0.0"},"servers":[{"url":"https://swanum.com"}],"paths":{"/comps/api/v1/vinted/sold":{"get":{"tags":["API"],"summary":"Sold Vinted items and price statistics (from our tracked history)","operationId":"vinted_sold_comps_api_v1_vinted_sold_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"description":"Search text, matched against titles","title":"Q"},"description":"Search text, matched against titles"},{"name":"country","in":"query","required":false,"schema":{"enum":["FR","DE","UK","IT","ES","NL","PL"],"type":"string","default":"FR","title":"Country"}},{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Brand"}},{"name":"size","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Size"}},{"name":"condition","in":"query","required":false,"schema":{"enum":["new","used","any"],"type":"string","default":"any","title":"Condition"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":90,"title":"Days"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":240,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VintedSoldResponse"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Payment Required"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too Many Requests"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/comps/api/v1/ebay/sold":{"get":{"tags":["API"],"summary":"Sold eBay listings and price statistics","operationId":"ebay_sold_comps_api_v1_ebay_sold_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"title":"Q"}},{"name":"marketplace","in":"query","required":false,"schema":{"enum":["US","UK","DE","CA","AU","FR","IT","ES"],"type":"string","default":"US","title":"Marketplace"}},{"name":"condition","in":"query","required":false,"schema":{"enum":["new","used","refurbished","for_parts","any"],"type":"string","default":"any","title":"Condition"}},{"name":"min_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Min Price"}},{"name":"max_price","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Max Price"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":90,"minimum":1,"default":90,"title":"Days"}},{"name":"category_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"eBay leaf category id, e.g. 139971 (Video Game Consoles). Only sales read since 2026-09-28 carry a category.","title":"Category Id"},"description":"eBay leaf category id, e.g. 139971 (Video Game Consoles). Only sales read since 2026-09-28 carry a category."},{"name":"exclude","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Comma-separated words to drop from titles","title":"Exclude"},"description":"Comma-separated words to drop from titles"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":240,"minimum":1,"default":50,"title":"Limit"}},{"name":"sort","in":"query","required":false,"schema":{"enum":["date_desc","price_asc","price_desc"],"type":"string","default":"date_desc","title":"Sort"}},{"name":"include_best_offer","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Best Offer"}},{"name":"fresh","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Fresh"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EbaySoldResponse"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Payment Required"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too Many Requests"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Service Unavailable"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/comps/api/v1/usage":{"get":{"tags":["API"],"summary":"Your plan and quota","operationId":"usage_comps_api_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/comps/api/v1/health":{"get":{"tags":["API"],"summary":"Per-source status from the canary monitor (no auth)","operationId":"health_comps_api_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"Coverage":{"properties":{"tracked_listings":{"type":"integer","title":"Tracked Listings"},"tracking_since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracking Since"},"days_tracked":{"type":"integer","title":"Days Tracked"},"disappeared_unknown":{"type":"integer","title":"Disappeared Unknown","description":"Listings that vanished without a 'sold' label — excluded from stats"},"note":{"type":"string","title":"Note"}},"type":"object","required":["tracked_listings","tracking_since","days_tracked","disappeared_unknown","note"],"title":"Coverage"},"EbayItem":{"properties":{"id":{"type":"string","title":"Id"},"title":{"type":"string","title":"Title"},"price":{"type":"number","title":"Price"},"currency":{"type":"string","title":"Currency"},"price_is_range":{"type":"boolean","title":"Price Is Range","default":false},"shipping":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Shipping"},"shipping_known":{"type":"boolean","title":"Shipping Known"},"total_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Price"},"best_offer_accepted":{"type":"boolean","title":"Best Offer Accepted"},"condition":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Condition"},"condition_normalized":{"type":"string","title":"Condition Normalized"},"sold_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sold Date"},"listing_type":{"anyOf":[{"type":"string","enum":["fixed_price","auction","best_offer"]},{"type":"null"}],"title":"Listing Type"},"bids":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bids"},"category_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Category Id","description":"eBay leaf category (from the item page); null for sales read before 2026-09-28"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"item_specifics":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Item Specifics","description":"The listing's item specifics, e.g. Model, Storage Capacity, UPC"},"url":{"type":"string","title":"Url"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"}},"type":"object","required":["id","title","price","currency","shipping","shipping_known","total_price","best_offer_accepted","condition","condition_normalized","sold_date","listing_type","bids","url","image_url"],"title":"EbayItem"},"EbaySoldResponse":{"properties":{"query":{"additionalProperties":true,"type":"object","title":"Query"},"source":{"type":"string","const":"ebay","title":"Source"},"cached":{"type":"boolean","title":"Cached"},"fetched_at":{"type":"string","title":"Fetched At"},"stats":{"$ref":"#/components/schemas/Stats"},"items":{"items":{"$ref":"#/components/schemas/EbayItem"},"type":"array","title":"Items"},"coverage":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Coverage"}},"type":"object","required":["query","source","cached","fetched_at","stats","items"],"title":"EbaySoldResponse"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"docs":{"type":"string","title":"Docs"}},"type":"object","required":["code","message","docs"],"title":"ErrorBody"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"SellThrough":{"properties":{"within_days":{"type":"integer","title":"Within Days"},"listings":{"type":"integer","title":"Listings","description":"Listings whose state at this horizon is known (sold, or seen for sale on time)"},"sold":{"type":"integer","title":"Sold"},"sold_pct":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sold Pct","description":"sold / listings, rounded; null below 15 listings"},"median_price_sold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Price Sold","description":"Last asking price of the ones that sold within the horizon; null below 5 on either side"},"median_price_unsold":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Price Unsold","description":"Last asking price of the ones still for sale at the horizon"}},"type":"object","required":["within_days","listings","sold","sold_pct","median_price_sold","median_price_unsold"],"title":"SellThrough"},"Stats":{"properties":{"count":{"type":"integer","title":"Count"},"currency":{"type":"string","title":"Currency"},"median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median"},"mean":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mean"},"p25":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P25"},"p75":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P75"},"min":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min"},"max":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max"},"outliers_removed":{"type":"integer","title":"Outliers Removed"},"median_with_shipping":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median With Shipping"},"sell_through_hint":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sell Through Hint"},"median_days_to_sell":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median Days To Sell","description":"Vinted: median of days_to_sell over the sales returned. Only items that sold are in it — see sell_through for how many don't"},"sell_through":{"anyOf":[{"items":{"$ref":"#/components/schemas/SellThrough"},"type":"array"},{"type":"null"}],"title":"Sell Through","description":"Vinted: of listings watched from (about) the hour they went up, how many had sold after 1, 3, 7, 14 and 30 days, and the prices of the ones that sold vs the ones still for sale"}},"type":"object","required":["count","currency","median","mean","p25","p75","min","max","outliers_removed"],"title":"Stats"},"UsageResponse":{"properties":{"plan":{"type":"string","title":"Plan"},"quota":{"type":"integer","title":"Quota"},"used":{"type":"integer","title":"Used"},"remaining":{"type":"integer","title":"Remaining"},"period_start":{"type":"string","title":"Period Start"},"resets_at":{"type":"string","title":"Resets At"}},"type":"object","required":["plan","quota","used","remaining","period_start","resets_at"],"title":"UsageResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VintedItem":{"properties":{"id":{"type":"string","title":"Id"},"title":{"type":"string","title":"Title"},"price":{"type":"number","title":"Price"},"currency":{"type":"string","title":"Currency"},"condition":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Condition"},"condition_normalized":{"type":"string","title":"Condition Normalized"},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand"},"size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Size"},"listed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Listed At","description":"When the listing went up, estimated from its listing number (Vinted numbers every listing in one rising sequence); about ±1 h"},"last_active_at":{"type":"string","title":"Last Active At","description":"Last time we saw it for sale; it sold after this"},"sold_detected_at":{"type":"string","title":"Sold Detected At","description":"When we saw the Sold label; it sold before this"},"days_to_sell":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Days To Sell","description":"sold_detected_at − listed_at in days: it sold within this long"},"url":{"type":"string","title":"Url"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"}},"type":"object","required":["id","title","price","currency","condition","condition_normalized","brand","size","listed_at","last_active_at","sold_detected_at","days_to_sell","url","image_url"],"title":"VintedItem"},"VintedSoldResponse":{"properties":{"query":{"additionalProperties":true,"type":"object","title":"Query"},"source":{"type":"string","const":"vinted","title":"Source"},"cached":{"type":"boolean","title":"Cached"},"fetched_at":{"type":"string","title":"Fetched At"},"stats":{"$ref":"#/components/schemas/Stats"},"coverage":{"$ref":"#/components/schemas/Coverage"},"items":{"items":{"$ref":"#/components/schemas/VintedItem"},"type":"array","title":"Items"}},"type":"object","required":["query","source","cached","fetched_at","stats","coverage","items"],"title":"VintedSoldResponse"}}}}