{"openapi":"3.0.0","info":{"title":"Rostrum Auction API","version":"1.0.15.0","description":"Run live auctions inside your product. Rostrum handles bid sequencing, anti-snipe timers, and webhook delivery.","contact":{"email":"hello@rostrum.live"}},"externalDocs":{"description":"Get your free API key at rostrum.live","url":"https://rostrum.live"},"servers":[{"url":"https://api.rostrum.live","description":"Production"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued at rostrum.live/signup"}},"schemas":{"Auction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"customer_id":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","enum":["standard","sealed_bid"],"default":"standard"},"unit":{"type":"string","description":"Currency or denomination label (e.g. AUD, USD, points). Opaque to Rostrum — passed through to webhooks and bid history as-is."},"reserve":{"type":"number","minimum":0},"min_increment":{"type":"number","minimum":0},"winners_count":{"type":"integer","minimum":1,"maximum":100},"ends_at":{"type":"string","format":"date-time"},"starts_at":{"type":"string","format":"date-time","nullable":true,"description":"Scheduled open time. Must be a future datetime. Used with the /schedule endpoint."},"extension_seconds":{"type":"integer","minimum":0},"trigger_threshold_seconds":{"type":"integer","minimum":0},"status":{"type":"string","enum":["DRAFT","OPEN","CLOSING","CLOSED","SCHEDULED","CANCELLED"]},"current_highest_bid":{"type":"number","description":"The current highest bid amount. 0 if no bids have been placed."},"current_highest_bidder_id":{"type":"string","nullable":true,"description":"The bidder_id of the current highest bidder. null until the first bid is placed."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Bid":{"type":"object","properties":{"id":{"type":"string"},"auction_id":{"type":"string","format":"uuid"},"bidder_id":{"type":"string"},"amount":{"type":"number"},"placed_at":{"type":"string","format":"date-time"}}},"Winner":{"type":"object","properties":{"rank":{"type":"integer"},"bidder_id":{"type":"string"},"amount":{"type":"number"},"bid_id":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"WebhookAuctionEnded":{"type":"object","description":"Fired when an auction closes. Also fires winner.confirmed (same shape) when winners.length > 0.","properties":{"type":{"type":"string","enum":["auction.ended","winner.confirmed"]},"auctionId":{"type":"string","format":"uuid"},"closedAt":{"type":"string","format":"date-time"},"winners":{"type":"array","items":{"$ref":"#/components/schemas/Winner"}}},"required":["type","auctionId","closedAt","winners"]}}},"security":[{"BearerAuth":[]}],"paths":{"/v1/me":{"get":{"summary":"API key introspection","description":"Returns the customer ID, tier, and quota usage for the authenticated API key.","operationId":"getMe","tags":["Account"],"responses":{"200":{"description":"API key info","content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"},"tier":{"type":"string","enum":["free","growth","enterprise"]},"quota_used":{"type":"integer"},"quota_limit":{"type":"integer"}},"required":["customer_id","tier","quota_used","quota_limit"]}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auctions":{"post":{"summary":"Create auction","description":"Creates a new auction in DRAFT status. The auction is not yet accepting bids.","operationId":"createAuction","tags":["Auctions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","ends_at"],"properties":{"title":{"type":"string","minLength":1,"maxLength":256,"description":"Display name for the auction."},"type":{"type":"string","enum":["standard","sealed_bid"],"default":"standard","description":"Auction type. standard = bids are public; sealed_bid = bids are hidden until close."},"unit":{"type":"string","maxLength":64,"default":"AUD","description":"Currency or denomination label (e.g. AUD, USD, points). Opaque to Rostrum — passed through to webhooks as-is."},"reserve":{"type":"number","minimum":0,"default":0,"description":"Minimum winning bid. Auction closes with no winner if not met."},"min_increment":{"type":"number","minimum":0,"default":0,"description":"Minimum amount each bid must exceed the current high bid."},"winners_count":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"Number of winners. Set > 1 for multi-winner auctions."},"ends_at":{"type":"string","format":"date-time","description":"When the auction closes (ISO 8601). Must be in the future."},"extension_seconds":{"type":"integer","minimum":0,"default":120,"description":"How many seconds to extend the deadline when a bid lands in the anti-snipe window."},"trigger_threshold_seconds":{"type":"integer","minimum":0,"default":60,"description":"Seconds before close that trigger the anti-snipe window."}}}}}},"responses":{"201":{"description":"Auction created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Auction"}}}},"401":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Tier restriction (feature not available on current tier)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Scheduler unavailable (EventBridge)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auctions/{id}":{"get":{"summary":"Get auction","description":"Returns the current state of an auction. Quota-exempt and cached.","operationId":"getAuction","tags":["Auctions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Auction state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Auction"}}}},"404":{"description":"Auction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Cancel auction","description":"Cancels an auction. Valid from DRAFT, OPEN, CLOSING, or SCHEDULED. CLOSED auctions cannot be cancelled.","operationId":"cancelAuction","tags":["Auctions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Auction cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Auction"}}}},"404":{"description":"Auction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Concurrent update — retry the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid transition (e.g. already CLOSED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auctions/{id}/start":{"post":{"summary":"Open auction immediately","description":"Transitions a DRAFT auction to OPEN, starting the timer immediately. Use /schedule instead to open at a future time.","operationId":"startAuction","tags":["Auctions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Auction opened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Auction"}}}},"404":{"description":"Auction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Concurrent update — retry the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auctions/{id}/schedule":{"post":{"summary":"Schedule auction open","description":"Schedules a DRAFT auction to open automatically at starts_at via EventBridge. starts_at must be a future datetime.","operationId":"scheduleAuction","tags":["Auctions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["starts_at"],"properties":{"starts_at":{"type":"string","format":"date-time","description":"When to open the auction (ISO 8601). Must be a future datetime."}}}}}},"responses":{"200":{"description":"Auction scheduled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Auction"}}}},"404":{"description":"Auction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid transition or starts_at not in future","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Scheduler unavailable (EventBridge)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auctions/{id}/bids":{"post":{"summary":"Place bid","description":"Places a bid on an OPEN or CLOSING auction. Bids below the current high bid plus min_increment are rejected.","operationId":"placeBid","tags":["Bids"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bidder_id","amount"],"properties":{"bidder_id":{"type":"string","minLength":1,"maxLength":128,"description":"Opaque identifier for the bidder in your system (user ID, username, Discord user ID, etc). Rostrum does not validate this."},"amount":{"type":"number","exclusiveMinimum":0,"description":"Bid amount in the auction's unit. Must exceed current high bid by at least min_increment."}}}}}},"responses":{"201":{"description":"Bid placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bid"}}}},"404":{"description":"Auction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Concurrent bid — retry the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Bid rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"not_open":{"value":{"error":"auction_not_open"}},"too_low":{"value":{"error":"bid_too_low"}},"below_reserve":{"value":{"error":"below_reserve"}}}}}}}},"get":{"summary":"Bid history","description":"Returns bids for an auction in reverse chronological order. Cursor-paginated using the bid ID.","operationId":"getBids","tags":["Bids"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"after","in":"query","required":false,"description":"Cursor for pagination. Pass the last bid ID from the previous page.","schema":{"type":"string","pattern":"^\\d+$"}},{"name":"limit","in":"query","required":false,"description":"Number of bids to return (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Bid list","content":{"application/json":{"schema":{"type":"object","properties":{"bids":{"type":"array","items":{"$ref":"#/components/schemas/Bid"}},"next_cursor":{"type":"string","nullable":true}}}}}},"404":{"description":"Auction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auctions/{id}/winner":{"get":{"summary":"Get winner(s)","description":"Returns the winner(s) of a CLOSED auction. Only available after the auction closes.","operationId":"getWinner","tags":["Auctions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Winner list","content":{"application/json":{"schema":{"type":"object","properties":{"winners":{"type":"array","items":{"$ref":"#/components/schemas/Winner"}}}}}}},"404":{"description":"Auction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Auction is not yet CLOSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}