{"openapi":"3.1.0","info":{"title":"RookVeyl intelligence auctions","version":"1.1.0","description":"Public catalog and single-lot scoped agents. Checkout requires an authorized Stripe payment; API keys cannot charge cards. No MCP or A2A endpoint."},"servers":[{"url":"https://rookveyl.com"}],"components":{"securitySchemes":{"AgentKey":{"type":"http","scheme":"bearer","description":"Buyer-issued key from /account. Checkout and delivery require the explicit additional permission."}},"schemas":{"Lot":{"type":"object","required":["id","title","mode","state","minimumBid","closesAt","url","snapshotHash"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"mode":{"type":"string","enum":["LIVE","TEST"]},"state":{"type":"string","enum":["open","closed","unsold"]},"minimumBid":{"type":"integer","description":"USD cents"},"closesAt":{"type":"integer","description":"Unix milliseconds"},"url":{"type":"string","format":"uri"},"snapshotHash":{"type":"string"},"preview":{"type":"array","items":{"type":"object"}},"packetInfo":{"type":"object","description":"Artifact format, record count, included fields, retrieval times and intended evaluation use"}}}}},"paths":{"/api/auctions":{"get":{"operationId":"searchAuctions","summary":"Search public auction previews; no credential required","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":100}},{"name":"mode","in":"query","schema":{"type":"string","enum":["LIVE","TEST","all"]}},{"name":"state","in":"query","schema":{"type":"string","enum":["open","closed","unsold"]}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"lotId","in":"query","schema":{"type":"string","description":"Retrieve one exact lot, including older lots beyond the latest-50 catalog"}}],"responses":{"200":{"description":"Latest 50 listings or exact lot; serverTime in Unix milliseconds. Buyer state appears only for signed-in browser users.","content":{"application/json":{"schema":{"type":"object","properties":{"lots":{"type":"array","items":{"$ref":"#/components/schemas/Lot"}},"serverTime":{"type":"integer"},"livePaymentReady":{"type":"boolean"}}}}}},"404":{"description":"Requested lot does not exist"},"503":{"description":"Catalog unavailable"}}}},"/api/announcements":{"get":{"operationId":"readAnnouncements","summary":"Open LIVE lots by default; poll every 15 minutes","parameters":[{"name":"mode","in":"query","schema":{"type":"string","enum":["LIVE","TEST","all"],"default":"LIVE"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Public feed with permanent URLs, USD minimumBidCents, deadlines and snapshot hashes"}}}},"/api/agents/bids":{"post":{"operationId":"placeAuthorizedBid","summary":"Bid on the authorized lot within its maximum","security":[{"AgentKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lotId","amountCents","clientKey"],"properties":{"lotId":{"type":"string"},"amountCents":{"type":"integer","minimum":100,"maximum":1000000},"clientKey":{"type":"string","minLength":1,"maxLength":100,"description":"Reuse this reference and exact payload on retries."}}}}}},"responses":{"200":{"description":"Accepted or duplicate bid; no payment taken"},"400":{"description":"Invalid amount or request"},"401":{"description":"Missing, expired or revoked key"},"403":{"description":"Wrong lot, missing permission, over-budget checkout or unpaid artifact"},"409":{"description":"Auction state or retry-reference conflict"},"503":{"description":"Service unavailable; retry safely"}}}},"/api/agents/checkout":{"post":{"operationId":"createWinningCheckout","summary":"Request Stripe checkout after winning; requires checkout/delivery permission","security":[{"AgentKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lotId"],"properties":{"lotId":{"type":"string"}}}}}},"responses":{"200":{"description":"Checkout URL only; does not authorize access or charge a card","content":{"application/json":{"schema":{"type":"object","properties":{"checkoutUrl":{"type":"string","format":"uri"},"paymentRequired":{"const":true},"paymentAuthority":{"const":false}}}}}},"401":{"description":"Missing, expired or revoked key"},"403":{"description":"Wrong lot, missing permission, over-budget checkout or unpaid artifact"},"409":{"description":"Auction state or retry-reference conflict"},"503":{"description":"Service unavailable; retry safely"}}}},"/api/agents/artifact":{"get":{"operationId":"retrievePaidPacket","summary":"Retrieve the paid packet and create an access receipt for the authorized lot","security":[{"AgentKey":[]}],"parameters":[{"name":"lotId","in":"query","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Sealed artifact and access receipt, after Stripe-confirmed payment"},"401":{"description":"Missing, expired or revoked key"},"403":{"description":"Wrong lot, missing permission, over-budget checkout or unpaid artifact"},"409":{"description":"Auction state or retry-reference conflict"},"503":{"description":"Service unavailable; retry safely"}}}},"/api/agents/receipts":{"get":{"operationId":"retrieveLotReceipts","summary":"Read this buyer's latest 50 receipts for the authorized lot","security":[{"AgentKey":[]}],"parameters":[{"name":"lotId","in":"query","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Payment and access receipts; empty until created"},"401":{"description":"Missing, expired or revoked key"},"403":{"description":"Wrong lot, missing permission, over-budget checkout or unpaid artifact"},"409":{"description":"Auction state or retry-reference conflict"},"503":{"description":"Service unavailable; retry safely"}}}}}}