{"openapi":"3.1.0","info":{"title":"UltraEdge Seller (vendor) API","version":"0.1.0","description":"Sellers, also called vendors in this API (the token scope and role are both named vendor; /swagger/seller is an alias): create, publish, pause and update listings, set the private floor, answer bids, counter, accept or decline, and manage deals."},"servers":[{"url":"https://api.ultraedge.ai","description":"production"}],"tags":[{"name":"System"},{"name":"Auth"},{"name":"Companies"},{"name":"Listings"},{"name":"Bids"},{"name":"Deals"},{"name":"Signals"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"website":{"type":["string","null"]},"phone":{"type":["string","null"]},"is_house":{"type":"boolean"},"verification_status":{"type":"string"},"status":{"type":"string"},"rating_avg":{"type":["number","null"]},"rating_count":{"type":"number"},"completed_deals":{"type":"number"},"created_at":{"type":"string"}},"required":["id","name","country","city","region","website","phone","is_house","verification_status","status","rating_avg","rating_count","completed_deals","created_at"]},"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"code":{"type":"string"},"instance":{"type":"string"}},"required":["type","title","status"]},"LoginRequest":{"type":"object","properties":{"email":{"type":"string","maxLength":200,"format":"email"},"password":{"type":"string","maxLength":200}},"required":["email","password"]},"CompanyPublic":{"type":"object","properties":{"ref":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"verified":{"type":"boolean"},"rating_avg":{"type":["number","null"]},"rating_count":{"type":"number"},"completed_deals":{"type":"number"},"location":{"type":"string"},"is_house":{"type":"boolean"},"member_since":{"type":"number"}},"required":["verified","rating_avg","rating_count","completed_deals","location","is_house","member_since"]},"ListingInput":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":200},"category":{"type":"string","minLength":2,"maxLength":60},"inventory_type":{"type":"string","enum":["new","used"]},"brand":{"type":"string","maxLength":80},"model":{"type":"string","maxLength":120},"mpn":{"type":"string","maxLength":80},"upc":{"type":"string","maxLength":20},"description":{"type":"string","maxLength":5000},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"USD"},"ask_cents":{"type":"integer","exclusiveMinimum":0,"maximum":1000000000},"pricing_mode":{"type":"string","enum":["fixed","negotiable"]},"floor_cents":{"type":["integer","null"],"minimum":0,"description":"Private seller floor. Never shown to buyers."},"visible_band_pct":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Optional visible negotiation band shown to buyers."},"max_counter_rounds":{"type":["integer","null"],"minimum":1,"maximum":20},"quantity_available":{"type":"integer","exclusiveMinimum":0,"maximum":10000000},"moq":{"type":"integer","exclusiveMinimum":0,"default":1},"location_city":{"type":"string","maxLength":80},"location_region":{"type":"string","maxLength":80},"location_country":{"type":"string","minLength":2,"maxLength":2,"default":"US"},"shipping_term":{"type":"string","maxLength":120},"payment_terms":{"type":"string","maxLength":200},"warranty":{"type":"string","maxLength":200},"packaging":{"type":"string","maxLength":80},"condition_new":{"type":"string","enum":["factory_sealed","open_box","new_other"]},"expires_at":{"type":"string","format":"date-time"},"is_house":{"type":"boolean","description":"Admins only. Marks UltraEdge house stock."},"used":{"$ref":"#/components/schemas/UsedLotDetails"}},"required":["title","category","inventory_type","ask_cents","pricing_mode","quantity_available"]},"UsedLotDetails":{"type":"object","properties":{"sale_format":{"type":"string","enum":["individual","bulk_lot"]},"functional_status":{"type":"string","enum":["tested_working","partially_tested","untested","for_parts"]},"cosmetic_grade":{"type":"string","enum":["A","B","C","custom"]},"refurbishment":{"type":"string","enum":["used","refurbished","seller_refurbished","manufacturer_refurbished"]},"data_status":{"type":"string","enum":["data_wiped","drive_removed","not_applicable","certification_available"]},"battery_health":{"type":"string","maxLength":40},"accessories":{"type":"string","maxLength":500},"lot_composition":{"type":"string","enum":["homogeneous","mixed"]},"manifest_media_id":{"type":"string","maxLength":100}},"required":["sale_format","functional_status","cosmetic_grade"]},"Signal":{"type":"object","properties":{"id":{"type":"string"},"scope":{"type":"string"},"severity":{"type":"string","enum":["good","info","urgent","error"]},"kind":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"entity_type":{"type":["string","null"]},"entity_id":{"type":["string","null"]},"data":{"type":["object","null"],"additionalProperties":{}},"expires_at":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","scope","severity","kind","title","body","entity_type","entity_id","data","expires_at","created_at"]},"ImportRow":{"type":"object","properties":{"mpn":{"type":"string","minLength":1,"maxLength":80},"title":{"type":"string","minLength":3,"maxLength":200},"category":{"type":"string","minLength":2,"maxLength":60},"inventory_type":{"type":"string","enum":["new","used"]},"condition":{"type":"string","maxLength":20,"description":"new | A | B | C (used grade)"},"brand":{"type":"string","maxLength":80},"model":{"type":"string","maxLength":120},"upc":{"type":"string","maxLength":20},"description":{"type":"string","maxLength":5000},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":10000000},"moq":{"type":"integer","exclusiveMinimum":0},"ask":{"type":"number","exclusiveMinimum":0},"ask_cents":{"type":"integer","exclusiveMinimum":0},"floor":{"type":["number","null"],"minimum":0},"floor_cents":{"type":["integer","null"],"minimum":0},"pricing_mode":{"type":"string","enum":["fixed","negotiable"]},"city":{"type":"string","maxLength":80},"region":{"type":"string","maxLength":80},"country":{"type":"string","minLength":2,"maxLength":2},"shipping_term":{"type":"string","maxLength":120},"payment_terms":{"type":"string","maxLength":200},"warranty":{"type":"string","maxLength":200}},"required":["mpn"]}},"parameters":{}},"paths":{"/v1/health":{"get":{"x-audience":["public","buyer","vendor","company-admin","admin","service"],"tags":["System"],"summary":"Liveness and database check","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"db":{"type":"string"},"version":{"type":"string"},"environment":{"type":"string"},"time":{"type":"string"}},"required":["status","db","version","environment","time"]}}}}}}},"/v1/auth/login":{"post":{"x-audience":["public","buyer","vendor","company-admin","admin","service"],"tags":["Auth"],"summary":"Log in with email and password","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"number"}},"required":["access_token","refresh_token","token_type","expires_in"]}}}},"401":{"description":"Bad credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/refresh":{"post":{"x-audience":["public","buyer","vendor","company-admin","admin","service"],"tags":["Auth"],"summary":"Exchange a refresh token for new tokens. Tokens rotate on every use; replaying a used token revokes the whole login family.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"refresh_token":{"type":"string","maxLength":2000}},"required":["refresh_token"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"refresh_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"number"}},"required":["access_token","refresh_token","token_type","expires_in"]}}}},"401":{"description":"Invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/logout":{"post":{"x-audience":["buyer","vendor","company-admin","admin","service"],"tags":["Auth"],"summary":"Revoke the refresh token's login family, or with all_devices every session (access tokens stop working immediately).","security":[{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"refresh_token":{"type":"string","maxLength":2000},"all_devices":{"type":"boolean"}}}}}},"responses":{"204":{"description":"Logged out"},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/me":{"get":{"x-audience":["buyer","vendor","company-admin","admin","service"],"tags":["Auth"],"summary":"Current user and company","security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"user":{},"company":{"$ref":"#/components/schemas/Company"}},"required":["company"]}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/companies/{id}":{"get":{"x-audience":["buyer","vendor","company-admin"],"tags":["Companies"],"summary":"Company profile. Full for own company or admins; anonymised public view otherwise.","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Company"},{"$ref":"#/components/schemas/CompanyPublic"}]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/activity":{"get":{"x-audience":["buyer","vendor","company-admin","service"],"tags":["Companies"],"summary":"My company's activity: every change it made (listings, bids, counters, deals, imports), newest first, with before and after values. Same rows the marketplace audit log holds, filtered to you.","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","maxLength":40},"required":false,"name":"entity_type","in":"query"},{"schema":{"type":"string","maxLength":60},"required":false,"name":"action","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"next_cursor":{"type":["string","null"]}},"required":["items","next_cursor"]}}}},"400":{"description":"Invalid cursor","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/listings":{"post":{"x-audience":["vendor","company-admin","service"],"tags":["Listings"],"summary":"Create a listing (draft)","security":[{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"Invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"x-audience":["public","buyer","vendor","company-admin","service"],"tags":["Listings"],"summary":"Search active listings (public). Owners can pass mine=true to see all statuses.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","maxLength":120},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","maxLength":60},"required":false,"name":"category","in":"query"},{"schema":{"type":"string","enum":["new","used"]},"required":false,"name":"inventory_type","in":"query"},{"schema":{"type":"string","enum":["fixed","negotiable"]},"required":false,"name":"pricing_mode","in":"query"},{"schema":{"type":"string","maxLength":80},"required":false,"name":"mpn","in":"query"},{"schema":{"type":"string","maxLength":80},"required":false,"name":"brand","in":"query"},{"schema":{"type":"string","maxLength":10},"required":false,"name":"grade","in":"query"},{"schema":{"type":"string","minLength":2,"maxLength":2},"required":false,"name":"country","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"min_price_cents","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"max_price_cents","in":"query"},{"schema":{"type":["integer","null"]},"required":false,"name":"min_quantity","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Only my company's listings, any status."},"required":false,"description":"Only my company's listings, any status.","name":"mine","in":"query"},{"schema":{"type":"string","maxLength":40,"pattern":"^[a-z0-9]+$","description":"Anonymous callers: which sandbox to search. Signed-in callers always see their own."},"required":false,"description":"Anonymous callers: which sandbox to search. Signed-in callers always see their own.","name":"sandbox","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"next_cursor":{"type":["string","null"]}},"required":["items","next_cursor"]}}}},"400":{"description":"Invalid cursor","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/listings/{id}":{"get":{"x-audience":["public","buyer","vendor","company-admin","service"],"tags":["Listings"],"summary":"Listing detail. Public projection never includes the seller's floor, company id, or name (when anonymity is on).","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"x-audience":["vendor","company-admin","service"],"tags":["Listings"],"summary":"Update own listing. Validated against the merged result; ask changes are recorded in price history; switching to fixed clears the floor.","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":200},"category":{"type":"string","minLength":2,"maxLength":60},"inventory_type":{"type":"string","enum":["new","used"]},"brand":{"type":"string","maxLength":80},"model":{"type":"string","maxLength":120},"mpn":{"type":"string","maxLength":80},"upc":{"type":"string","maxLength":20},"description":{"type":"string","maxLength":5000},"currency":{"type":"string","minLength":3,"maxLength":3,"default":"USD"},"ask_cents":{"type":"integer","exclusiveMinimum":0,"maximum":1000000000},"pricing_mode":{"type":"string","enum":["fixed","negotiable"]},"floor_cents":{"type":["integer","null"],"minimum":0,"description":"Private seller floor. Never shown to buyers."},"visible_band_pct":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Optional visible negotiation band shown to buyers."},"max_counter_rounds":{"type":["integer","null"],"minimum":1,"maximum":20},"quantity_available":{"type":"integer","exclusiveMinimum":0,"maximum":10000000},"moq":{"type":"integer","exclusiveMinimum":0,"default":1},"location_city":{"type":"string","maxLength":80},"location_region":{"type":"string","maxLength":80},"location_country":{"type":"string","minLength":2,"maxLength":2,"default":"US"},"shipping_term":{"type":"string","maxLength":120},"payment_terms":{"type":"string","maxLength":200},"warranty":{"type":"string","maxLength":200},"packaging":{"type":"string","maxLength":80},"condition_new":{"type":"string","enum":["factory_sealed","open_box","new_other"]},"expires_at":{"type":"string","format":"date-time"},"is_house":{"type":"boolean","description":"Admins only. Marks UltraEdge house stock."},"used":{"$ref":"#/components/schemas/UsedLotDetails"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"Invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"x-audience":["vendor","company-admin","service"],"tags":["Listings"],"summary":"Remove a listing","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Wrong status","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/listings/{id}/publish":{"post":{"x-audience":["vendor","company-admin","service"],"tags":["Listings"],"summary":"Publish a draft or paused listing. Goes to admin review or straight to active depending on listings.review_required. Only an admin can move a listing out of review.","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"Expired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Wrong status","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/listings/{id}/pause":{"post":{"x-audience":["vendor","company-admin","service"],"tags":["Listings"],"summary":"Pause an active listing","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Wrong status","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/listings/{id}/price-history":{"get":{"x-audience":["public","buyer","vendor","company-admin","service"],"tags":["Listings"],"summary":"Ask-price changes and closed-deal prices for an active listing (owners see their own in any state). Closed-deal prices appear once price_history.min_deals_to_show deals exist for the MPN.","parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"next_cursor":{"type":["string","null"]}},"required":["items","next_cursor"]}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/bids":{"get":{"x-audience":["buyer","vendor","company-admin"],"tags":["Bids"],"summary":"My bids (role=buyer) or bids on my listings (role=vendor). Auto-declined bids never appear in the vendor view.","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["buyer","vendor","seller"],"default":"buyer","description":"buyer: my bids. vendor (alias: seller): bids on my listings."},"required":false,"description":"buyer: my bids. vendor (alias: seller): bids on my listings.","name":"role","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"listing_id","in":"query"},{"schema":{"type":"string","maxLength":20},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"next_cursor":{"type":["string","null"]}},"required":["items","next_cursor"]}}}},"400":{"description":"Invalid cursor","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/bids/{id}":{"get":{"x-audience":["buyer","vendor","company-admin"],"tags":["Bids"],"summary":"Bid detail with counter history","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/bids/{id}/counter":{"post":{"x-audience":["buyer","vendor","company-admin"],"tags":["Bids"],"summary":"Counter the current price. Vendor counters sit between the buyer's last price and the ask (or between ask and bid when the bid is above ask); buyer counters between their last price and the vendor's last counter. Rounds are limited by the max snapshotted on the bid.","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"price_cents":{"type":"integer","exclusiveMinimum":0,"maximum":1000000000},"quantity":{"type":"integer","exclusiveMinimum":0},"message":{"type":"string","maxLength":1000},"expires_in_hours":{"type":"integer","minimum":1,"maximum":720}},"required":["price_cents"]}}}},"responses":{"201":{"description":"Counter recorded","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Not your turn, bid closed, or concurrent counter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Counter rule violated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/bids/{id}/accept":{"post":{"x-audience":["buyer","vendor","company-admin"],"tags":["Bids"],"summary":"Accept the current price. The vendor accepts a bid or buyer counter; the buyer accepts a vendor counter. Re-validates listing, stock, eligibility and expiry, then atomically creates the Deal, reserves stock, snapshots the fee and rules, and reveals both company names.","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"201":{"description":"Deal created","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Bid not open, stock gone, or concurrent accept","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/bids/{id}/decline":{"post":{"x-audience":["vendor","company-admin"],"tags":["Bids"],"summary":"Vendor declines a bid","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Bid not open","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/deals":{"get":{"x-audience":["buyer","vendor","company-admin"],"tags":["Deals"],"summary":"Deals where my company is buyer or vendor","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"next_cursor":{"type":["string","null"]}},"required":["items","next_cursor"]}}}},"400":{"description":"Invalid cursor","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/deals/{id}":{"get":{"x-audience":["buyer","vendor","company-admin"],"tags":["Deals"],"summary":"Deal detail with status history and the frozen commercial snapshot","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/deals/{id}/transition":{"post":{"x-audience":["buyer","vendor","company-admin"],"tags":["Deals"],"summary":"Move a deal along the state machine: accepted > payment_pending > payment_confirmed > ready_released > shipped_picked_up > received > completed. Either party may dispute from any open state or cancel before payment is confirmed; only the buyer completes (from received); only an admin resolves a dispute.","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","enum":["payment_pending","payment_confirmed","ready_released","shipped_picked_up","received","completed","disputed","cancelled"]},"note":{"type":"string","maxLength":1000}},"required":["to"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Illegal transition, escrow required, or concurrent change","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/deals/{id}/escrow":{"post":{"x-audience":["buyer","vendor","company-admin"],"tags":["Deals"],"summary":"Request partner escrow for this deal (allowed when the deal's escrow mode is optional or required). Provider adapter is set by escrow.provider.","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Escrow off or deal not eligible","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/signals":{"get":{"x-audience":["buyer","vendor","company-admin","admin"],"tags":["Signals"],"summary":"My company's signal feed, newest first, with the unread count. Severity is good | info | urgent | error and decides the colour everywhere. First page comes from the in-memory hot list; use cursor for history (30 days).","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["good","info","urgent","error"],"description":"Only this severity (history pages only)"},"required":false,"description":"Only this severity (history pages only)","name":"severity","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Signal"}},"next_cursor":{"type":["string","null"]},"unread":{"type":"integer"},"stream":{"type":"string","description":"How to open the live stream"}},"required":["items","next_cursor","unread","stream"]}}}},"400":{"description":"Invalid cursor","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/signals/seen":{"post":{"x-audience":["buyer","vendor","company-admin","admin"],"tags":["Signals"],"summary":"Mark signals seen up to a cursor (default: everything). The unread badge counts only newer items.","security":[{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cursor":{"type":"string","description":"Mark seen up to this item cursor (created_at|id). Omit to mark everything seen."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"unread":{"type":"integer"}},"required":["unread"]}}}}}}},"/v1/signals/stream-token":{"post":{"x-audience":["buyer","vendor","company-admin","admin"],"tags":["Signals"],"summary":"A 60-second ticket for the WebSocket stream. Open wss://<api>/v1/signals/stream?t=<token>. The socket sends {type:'hello', items} then {type:'signals', items:[...]} as they happen; send 'ping' for 'pong'.","security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"expires_in":{"type":"integer"},"url":{"type":"string"}},"required":["token","expires_in","url"]}}}}}}},"/v1/market/signals":{"get":{"x-audience":["public","buyer","vendor","company-admin","admin","service"],"tags":["Signals"],"summary":"Anonymised public market feed: new listings, price drops, closed prices, scarcity, newly verified companies. No token needed. Cached for 5 seconds at the edge; stream at wss://<api>/v1/market/stream.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":200},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Signal"}},"next_cursor":{"type":["string","null"]}},"required":["items","next_cursor"]}}}},"400":{"description":"Invalid cursor","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/watchlist":{"get":{"x-audience":["buyer","vendor","company-admin"],"tags":["Signals"],"summary":"MPNs and listings my company watches. Market signals about them land in my feed as watch.* signals.","security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["items"]}}}}}},"post":{"x-audience":["buyer","vendor","company-admin"],"tags":["Signals"],"summary":"Watch an MPN or a listing","security":[{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mpn":{"type":"string","minLength":1,"maxLength":80},"listing_id":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"404":{"description":"Listing not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Already watching","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/watchlist/{id}":{"delete":{"x-audience":["buyer","vendor","company-admin"],"tags":["Signals"],"summary":"Stop watching","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Removed"},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/assets/{slot}":{"get":{"x-audience":["public","buyer","vendor","company-admin","admin","service"],"tags":["System"],"summary":"A generated brand asset by slot (e.g. role-buyer). ?n=1 for the second variant.","parameters":[{"schema":{"type":"string","pattern":"^[a-z0-9-]{2,60}$"},"required":true,"name":"slot","in":"path"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":7,"default":0},"required":false,"name":"n","in":"query"}],"responses":{"200":{"description":"Image"},"304":{"description":"Not modified"},"404":{"description":"No image for that slot","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/listings/import":{"post":{"x-audience":["vendor","company-admin","service"],"tags":["Listings"],"summary":"Import or update listings from a spreadsheet. JSON rows, or a text/csv body whose header names the columns (mpn, title, category, inventory_type, condition, brand, model, quantity, moq, ask, floor, pricing_mode, city, region, country, description…). Matched by mpn within your company.","security":[{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/ImportRow"},"minItems":1,"maxItems":100000},"publish":{"type":"boolean","default":true,"description":"Publish new listings after creating them (subject to review rules)."},"dry_run":{"type":"boolean","default":false,"description":"Validate and report without writing."}},"required":["rows"]}},"text/csv":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Per-row report","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"400":{"description":"Invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Vendor role required or import disabled","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Too many rows","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/finance/statement":{"get":{"x-audience":["buyer","vendor","company-admin","admin"],"tags":["Finance"],"summary":"My company's statement for a window: GMV bought and sold, fees accrued, paid, outstanding and overdue, with the entries. Admins pass company_id.","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{1,3}d$","default":"30d"},"required":false,"name":"window","in":"query"},{"schema":{"type":"string","format":"uuid"},"required":false,"name":"company_id","in":"query"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"403":{"description":"Not your company","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/finance/deals/{id}/invoice":{"get":{"x-audience":["buyer","vendor","company-admin","admin"],"tags":["Finance"],"summary":"Invoice document for a deal: issuer, bill-to, goods lines, fee line, escrow state, due date and status. Parties and admins only.","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Invoice","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"webhooks":{}}