{"openapi":"3.1.0","info":{"title":"UltraEdge Buyer API","version":"0.1.0","description":"Verified buyer companies: search listings, place bids (auto-declined under the seller's private floor), counter, accept, withdraw, and move deals along."},"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"]},"BidInput":{"type":"object","properties":{"quantity":{"type":"integer","exclusiveMinimum":0},"price_cents":{"type":"integer","exclusiveMinimum":0,"maximum":1000000000},"expires_in_hours":{"type":"integer","minimum":1,"maximum":720},"message":{"type":"string","maxLength":1000}},"required":["quantity","price_cents"]},"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"]}},"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":{"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"}}}}}}},"/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/listings/{id}/bids":{"post":{"x-audience":["buyer","company-admin"],"tags":["Bids"],"summary":"Place a bid on a negotiable listing. Bids under the seller's private floor are auto-declined with a plain message; the seller never sees them. Rate-limited per buyer and probe-limited per listing per day.","security":[{"bearer":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BidInput"}}}},"responses":{"200":{"description":"Replay of an idempotent request","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"201":{"description":"Bid recorded (status open or auto_declined)","content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":{}}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Bid rule violated (code says which) or Idempotency-Key reused with a different request","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}/withdraw":{"post":{"x-audience":["buyer","company-admin"],"tags":["Bids"],"summary":"Buyer withdraws 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/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":{}}