{"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 200,000+ closed auctions, nearly all from the last 12 months, 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"},"x-versioning":{"scheme":"URL path (/api/v1). A breaking change ships as /api/v2; /api/v1 is never broken in place.","deprecationPolicy":"A deprecated endpoint returns the RFC 8594 `Deprecation` header with the date it was deprecated, and `Sunset` with the date it stops responding. Sunset is never less than 180 days after Deprecation, and both are announced at https://bidprowl.com/developers before they are sent.","contact":"hello@bidprowl.com"}},"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"}}},"Error":{"type":"object","required":["error","code","docs"],"properties":{"error":{"type":"string","description":"Human-readable message."},"code":{"type":"string","description":"Machine-readable code. Branch on this, never on `error`.","enum":["missing_api_key","invalid_api_key","forbidden","not_found","invalid_request","burst_rate_exceeded","monthly_quota_exceeded","internal_error"]},"docs":{"type":"string","format":"uri"},"upgrade":{"type":"string","format":"uri","description":"Present only when upgrading actually resolves the failure."}}}},"headers":{"RateLimit-Limit":{"description":"Calls allowed in the current monthly window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Calls left in the current monthly window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the monthly window resets (delta-seconds, per the RFC draft).","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying. Sent on every 429.","schema":{"type":"integer"}}},"responses":{"Unauthorized":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The key is valid but the plan does not include this data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such listing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Per-minute burst limit or monthly quota exhausted. Read Retry-After, and RateLimit-* to self-throttle before you get here.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"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"}}}}}},"400":{"description":"Malformed query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/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"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/sources":{"get":{"operationId":"listSources","summary":"Tracked government auction sources with live counts","responses":{"200":{"description":"Sources with live listing counts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"name":{"type":"string"},"live_count":{"type":"integer"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/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","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SoldStats"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/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","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"flip_score":{"type":"integer","minimum":0,"maximum":100},"factors":{"type":"object","additionalProperties":{"type":"number"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/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":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}