{"openapi":"3.1.0","info":{"title":"BidProwl API","version":"1.0.0","description":"US government surplus auctions: live listings from 27 official sources with ZIP-radius search, sold-price comparables from 250,000+ closed auctions back to 2018, and Flip Scores. Free tier: 1,000 calls/month. Get a key at https://bidprowl.com/account/api-keys.","contact":{"email":"hello@bidprowl.com","url":"https://bidprowl.com/developers"}},"servers":[{"url":"https://bidprowl.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (bp_live_...) from bidprowl.com/account/api-keys"}},"schemas":{"Listing":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"category":{"type":"string","description":"One of: vehicles, heavy-equipment, electronics, office-furniture, tools-industrial, medical-scientific, military-surplus, real-estate, seized-property, other"},"source":{"type":"string","description":"Source key, e.g. govdeals"},"source_name":{"type":"string"},"state":{"type":["string","null"],"description":"2-letter US state code"},"city":{"type":["string","null"]},"zip":{"type":["string","null"]},"current_bid_cents":{"type":["integer","null"]},"buy_now_cents":{"type":["integer","null"]},"starting_bid_cents":{"type":["integer","null"]},"num_bids":{"type":"integer"},"flip_score":{"type":["integer","null"],"description":"BidProwl deal score"},"condition_grade":{"type":["string","null"]},"image_url":{"type":["string","null"]},"start_date":{"type":["string","null"],"format":"date-time"},"end_date":{"type":["string","null"],"format":"date-time"},"status":{"type":"string"},"bidprowl_url":{"type":"string"},"source_url":{"type":"string","description":"Official auction page where bidding happens"}}},"SoldStats":{"type":"object","properties":{"median_cents":{"type":"integer"},"average_cents":{"type":"integer"},"min_cents":{"type":"integer"},"max_cents":{"type":"integer"},"sold_count":{"type":"integer"},"avg_bids":{"type":"number"}}}}},"paths":{"/api/v1/listings":{"get":{"operationId":"searchListings","summary":"Search live government auction listings","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Keyword search"},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string"},"description":"2-letter code"},{"name":"source","in":"query","schema":{"type":"string"}},{"name":"zip","in":"query","schema":{"type":"string"},"description":"Center of a radius search"},{"name":"radius_miles","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"price_min","in":"query","schema":{"type":"number"},"description":"USD"},{"name":"price_max","in":"query","schema":{"type":"number"},"description":"USD"},{"name":"sort","in":"query","schema":{"type":"string","enum":["ending_soon","newest","price_low","price_high","most_bids","best_deals"]}},{"name":"no_bids","in":"query","schema":{"type":"boolean"}},{"name":"buy_now","in":"query","schema":{"type":"boolean"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Paginated listings","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}}}},"/api/v1/listings/{id}":{"get":{"operationId":"getListing","summary":"One listing by id or slug","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The listing","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"404":{"description":"Not found"}}}},"/api/v1/sources":{"get":{"operationId":"listSources","summary":"Tracked government auction sources with live counts","responses":{"200":{"description":"Sources with live listing counts"}}}},"/api/v1/comps":{"get":{"operationId":"getSoldComps","summary":"Sold-price comparables","description":"Category+state aggregates for every key. Item-level percentiles (item=) and per-listing comps with resale margin (listing_id=) require Pro or Pro+.","parameters":[{"name":"listing_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"item","in":"query","schema":{"type":"string"},"description":"Tracked item slug, e.g. forklift"},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Comparables"},"403":{"description":"Item-level comps need Pro/Pro+"}}}},"/api/v1/flip-score/{id}":{"get":{"operationId":"getFlipScore","summary":"Flip Score with factor breakdown and resale margin (Pro/Pro+)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Score detail"},"403":{"description":"Needs Pro/Pro+"}}}},"/api/v1/export":{"get":{"operationId":"exportListingsCsv","summary":"CSV export of a filtered search, max 5,000 rows (Pro+ only)","responses":{"200":{"description":"CSV file","content":{"text/csv":{}}},"403":{"description":"Needs the Pro+ API plan"}}}}}}