{"openapi":"3.1.0","info":{"title":"Carena public auction API","version":"1.0.0","description":"Search Copart, IAAI and ADESA vehicles, and bid with money wired to a Carena wallet. Browsing needs no account. Account actions need an OAuth sign-in by the account holder or a personal API key: they sign in at https://auctions.autocarena.com, opens Account → AI agents, and creates one. Send it as `Authorization: Bearer ca_...`. Keys always have `read`; `bid` allows bids and watchlist changes (connected apps get watchlist changes only: their bids are confirmed by the person on Carena); `withdraw` allows withdrawing to the bank (personal API keys only: connected apps cannot withdraw). Bids are 1:1 with the wallet: open bids together can never exceed the balance. Carena bids on behalf of the account holder at the auction and marks each bid placed, won (with the final charge) or lost. A win costs the final price, the auction fees and a flat $100 Carena fee. Shipping is quoted after the win and taken from the wallet too; when the wallet goes below zero the person wires what they owe. Nobody can buy a vehicle located in their own state. An MCP server with the same actions is at https://auctions.autocarena.com/mcp."},"servers":[{"url":"https://auctions.autocarena.com/api/public-auction"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Personal API key (ca_...) from Account → AI agents, an OAuth access token, or a Firebase ID token."},"oauth":{"type":"oauth2","description":"Authorization code with PKCE (S256); apps register at /oauth/register. The person logs in and approves on our consent page.","flows":{"authorizationCode":{"authorizationUrl":"https://auctions.autocarena.com/oauth/authorize","tokenUrl":"https://auctions.autocarena.com/oauth/token","refreshUrl":"https://auctions.autocarena.com/oauth/token","scopes":{"read":"See vehicles, wallet, bids and watchlist","bid":"Place bids and Buy Now offers; change the watchlist"}}}}},"schemas":{"Error":{"type":"object","properties":{"success":{"const":false},"error":{"type":"string"},"field":{"type":"string"},"errorCode":{"type":"string"}}},"Lot":{"type":"object","description":"A vehicle. Main fields shown; responses carry more (images, damage, title document, location).","properties":{"lotId":{"type":"string"},"site":{"type":"string"},"vin":{"type":"string"},"title":{"type":"string"},"year":{"type":"integer"},"make":{"type":"string"},"model":{"type":"string"},"odometer":{"type":"number"},"primaryDamage":{"type":"string"},"location":{"type":"string"},"stateCode":{"type":"string"},"auctionDate":{"type":"string","format":"date-time"},"currentBid":{"type":"number"},"buyNowPrice":{"type":"number"},"canBid":{"type":"boolean"},"canBuyNow":{"type":"boolean"}}},"Bid":{"type":"object","properties":{"id":{"type":"string"},"lotId":{"type":"string"},"site":{"type":"string"},"requestType":{"enum":["max_bid","buy_now"]},"amount":{"type":"number"},"status":{"enum":["open","placed","won","lost"],"description":"open: received; placed: entered at the auction; won/lost: closed."},"chargeAmount":{"type":["number","null"],"description":"What a win cost (price + auction fees), taken from the wallet."},"transport":{"type":["object","null"],"properties":{"status":{"enum":["quote_pending","quoted","scheduled","picked_up","delivered"]},"quoteAmount":{"type":["number","null"]}}},"lot":{"$ref":"#/components/schemas/Lot"},"createdAt":{"type":"string","format":"date-time"}}},"Account":{"type":"object","properties":{"email":{"type":"string"},"profileComplete":{"type":"boolean","description":"Name and address are on file. Bids need it; the account holder adds it on the website."},"homeState":{"type":["string","null"],"description":"State of the address on file. Vehicles located there cannot be bought."},"actionsNeeded":{"type":"array","items":{"type":"string"},"description":"Plain next steps for the person, such as wiring what they owe."},"wallet":{"type":"object","properties":{"balance":{"type":"number"},"holds":{"type":"number","description":"Held by open bids."},"available":{"type":"number","description":"What you can still bid or withdraw."},"owed":{"type":"number"}}},"wireInstructions":{"type":"object","description":"The bidder's own bank details. A wire sent here lands in the wallet. Wires only, no ACH.","properties":{"bankName":{"type":"string"},"routingNumber":{"type":"string"},"accountNumber":{"type":"string"},"accountHolderName":{"type":"string"}}},"bids":{"type":"array","items":{"$ref":"#/components/schemas/Bid"}},"watchlist":{"type":"array","items":{"type":"object","properties":{"lotId":{"type":"string"},"site":{"type":"string"},"lot":{"$ref":"#/components/schemas/Lot"}}}}}}}},"paths":{"/cars":{"get":{"operationId":"searchVehicles","summary":"Search vehicles","parameters":[{"name":"name","in":"query","schema":{"type":"string"},"description":"Keywords: make, model, year."},{"name":"make","in":"query","schema":{"type":"array","items":{"type":"string"}},"description":"Exact make as the catalog spells it (repeat for variants, e.g. make=Toyota&make=TOYOTA). The MCP search_vehicles tool matches any spelling."},{"name":"model","in":"query","schema":{"type":"array","items":{"type":"string"}},"description":"Exact model as the catalog spells it; repeatable like make."},{"name":"domain_id","in":"query","schema":{"enum":["copart_com","iaai_com","adesa"]},"description":"One auction house."},{"name":"year","in":"query","schema":{"type":"integer"},"description":"One model year."},{"name":"from_year","in":"query","schema":{"type":"integer"}},{"name":"to_year","in":"query","schema":{"type":"integer"}},{"name":"odometer_from_mi","in":"query","schema":{"type":"integer"}},{"name":"odometer_to_mi","in":"query","schema":{"type":"integer"}},{"name":"odometer_unknown","in":"query","schema":{"enum":["0","1"]},"description":"0 leaves out vehicles with no odometer reading."},{"name":"buy_now_price_from","in":"query","schema":{"type":"number"}},{"name":"buy_now_price_to","in":"query","schema":{"type":"number"}},{"name":"bid_price_from","in":"query","schema":{"type":"number"},"description":"Current bid, US dollars."},{"name":"bid_price_to","in":"query","schema":{"type":"number"}},{"name":"body_type","in":"query","schema":{"type":"string"},"description":"1 sedan, 2 wagon, 3 coupe, 4 pickup, 5 SUV, 6 convertible, 7 van, 11 hatchback, 12 roadster."},{"name":"document_title","in":"query","schema":{"enum":["clean_clear","salvage"]},"description":"Clean title or salvage/rebuildable; both by default."},{"name":"damage","in":"query","schema":{"type":"string"},"description":"Primary or secondary damage, e.g. Front End, Hail, Flood, Rear End, Minor Dent/Scratches."},{"name":"condition","in":"query","schema":{"type":"string"},"description":"0 runs and drives, 6 engine starts, 3 does not run, 1 for repair, 2 for parts."},{"name":"fuel_type","in":"query","schema":{"type":"string"},"description":"gasoline, 1 diesel, 2 electric, 3 hybrid, 6 flexible, 7 hydrogen."},{"name":"transmission","in":"query","schema":{"enum":["1","2"]},"description":"1 automatic, 2 manual."},{"name":"drive_wheel","in":"query","schema":{"enum":["1","2","3"]},"description":"1 rear, 2 front, 3 all-wheel."},{"name":"color","in":"query","schema":{"type":"string"},"description":"e.g. Black, White, Silver, Gray, Red, Blue."},{"name":"cylinders","in":"query","schema":{"type":"integer"}},{"name":"engine_name","in":"query","schema":{"type":"string"},"description":"Text in the engine description, e.g. 2.5L or V8."},{"name":"state_code","in":"query","schema":{"type":"string"},"description":"Two-letter US state of the yard."},{"name":"origin_zip","in":"query","schema":{"type":"string"},"description":"US ZIP for a distance search (with radius_miles)."},{"name":"radius_miles","in":"query","schema":{"type":"integer","maximum":3000}},{"name":"exclude_state_code","in":"query","schema":{"type":"string"},"description":"Leave out one state. Pass the account homeState: vehicles there cannot be bought."},{"name":"buy_now","in":"query","schema":{"enum":["1","2"]},"description":"1: only lots with Buy Now; 2: only lots open for bidding."},{"name":"sale_date_in_days","in":"query","schema":{"type":"integer"},"description":"Sale within this many days."},{"name":"sale_date_from","in":"query","schema":{"type":"string","format":"date"},"description":"Sale on or after this date."},{"name":"sort","in":"query","schema":{"enum":["buy_now_price_low","buy_now_price_high","current_bid_low","current_bid_high","sale_soonest","miles_low","year_newest","year_oldest"]},"description":"Default: buyable now first. With miles_low, also pass odometer_from_mi=10&odometer_unknown=0: some feeds record unknown readings as 0 or 1 mile."},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"size","in":"query","schema":{"type":"integer","default":60,"maximum":60}}],"responses":{"200":{"description":"A page of vehicles.","content":{"application/json":{"schema":{"type":"object","properties":{"lots":{"type":"array","items":{"$ref":"#/components/schemas/Lot"}},"page":{"type":"integer"},"pages":{"type":"integer"},"total":{"type":"integer"}}}}}}}}},"/cars/search":{"get":{"operationId":"findVehicle","summary":"Find one vehicle by exact lot number or VIN","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"site","in":"query","required":false,"schema":{"type":"string"},"description":"The lot's `site` as search returns it (copart_com, iaai_com, ...). Include it when you have it."}],"responses":{"200":{"description":"The vehicle.","content":{"application/json":{"schema":{"type":"object","properties":{"lot":{"$ref":"#/components/schemas/Lot"}}}}}},"404":{"description":"No open vehicle matches.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/cars/{lotId}":{"get":{"operationId":"getVehicle","summary":"Vehicle details","parameters":[{"name":"lotId","in":"path","required":true,"schema":{"type":"string"},"description":"Auction lot number (Copart/IAAI) or ADESA vehicle id."},{"name":"site","in":"query","required":false,"schema":{"type":"string"},"description":"The lot's `site` as search returns it (copart_com, iaai_com, ...). Include it when you have it."}],"responses":{"200":{"description":"The vehicle.","content":{"application/json":{"schema":{"type":"object","properties":{"lot":{"$ref":"#/components/schemas/Lot"}}}}}},"404":{"description":"Sold, ended, or unknown.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/me":{"get":{"operationId":"getAccount","summary":"Wallet, wire instructions, bids and watchlist","security":[{"apiKey":[]}],"responses":{"200":{"description":"The account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"400":{"description":"Invalid request. `error` says what to fix; `field` names the bad field when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bids":{"post":{"operationId":"placeBid","summary":"Place or raise a max bid, or make a Buy Now offer (needs `bid`)","description":"Holds the amount in the wallet. A second max bid on the same lot raises the first. Send an Idempotency-Key header so a retry cannot place a second bid.","security":[{"apiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lotId","site","requestType"],"properties":{"lotId":{"type":"string"},"site":{"type":"string"},"requestType":{"enum":["max_bid","buy_now"]},"amount":{"type":"number","description":"Whole dollars, for max_bid. Buy Now uses the listed price."}}}}}},"responses":{"200":{"description":"Bid recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"bidId":{"type":"string"},"amount":{"type":"number"},"replayed":{"type":"boolean"}}}}}},"400":{"description":"Invalid request. `error` says what to fix; `field` names the bad field when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/watchlist":{"post":{"operationId":"addToWatchlist","summary":"Save a vehicle (needs `bid`)","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["lotId","site"],"properties":{"lotId":{"type":"string"},"site":{"type":"string"}}}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request. `error` says what to fix; `field` names the bad field when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/watchlist/{lotId}":{"delete":{"operationId":"removeFromWatchlist","summary":"Remove a saved vehicle (needs `bid`)","security":[{"apiKey":[]}],"parameters":[{"name":"lotId","in":"path","required":true,"schema":{"type":"string"},"description":"Auction lot number (Copart/IAAI) or ADESA vehicle id."},{"name":"site","in":"query","required":true,"schema":{"type":"string"},"description":"The lot's `site` as search returns it (copart_com, iaai_com, ...). Include it when you have it."}],"responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request. `error` says what to fix; `field` names the bad field when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/withdraw":{"post":{"operationId":"withdraw","summary":"Send the available balance back to the bidder's bank (personal API key with `withdraw`; connected apps cannot)","description":"Stripe emails the account holder for bank details if it doesn't have them.","security":[{"apiKey":[]}],"responses":{"200":{"description":"Withdrawal started.","content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number"}}}}}},"400":{"description":"Invalid request. `error` says what to fix; `field` names the bad field when there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired, or revoked credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key lacks the permission this needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}