{"openapi":"3.1.0","info":{"title":"UltraEdge Public API","version":"0.1.0","description":"Visitors without an account: search and read active listings, price history, and sign up or log in. No bearer token needed."},"servers":[{"url":"https://api.ultraedge.ai","description":"production"}],"tags":[{"name":"System"},{"name":"Auth"},{"name":"Listings"},{"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"]},"RegisterRequest":{"type":"object","properties":{"email":{"type":"string","maxLength":200,"format":"email"},"password":{"type":"string","minLength":12,"maxLength":200},"full_name":{"type":"string","maxLength":120},"company":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120},"country":{"type":"string","minLength":2,"maxLength":2,"default":"US"},"city":{"type":"string","maxLength":80},"region":{"type":"string","maxLength":80},"website":{"type":"string","maxLength":300,"format":"uri"},"phone":{"type":"string","maxLength":40}},"required":["name"]}},"required":["email","password","company"]},"LoginRequest":{"type":"object","properties":{"email":{"type":"string","maxLength":200,"format":"email"},"password":{"type":"string","maxLength":200}},"required":["email","password"]},"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/register":{"post":{"x-audience":["public","company-admin"],"tags":["Auth"],"summary":"Register a company and its first user (company admin). Honours signup.mode: invite_only refuses; open verifies immediately; open_manual_approval waits for admin verification.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}}},"responses":{"201":{"description":"Created","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"},"user":{},"company":{"$ref":"#/components/schemas/Company"}},"required":["access_token","refresh_token","token_type","expires_in","company"]}}}},"400":{"description":"Invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Registration closed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Email exists","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/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/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/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/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"}}}}}}}},"webhooks":{}}