post/api/auctions
Create an auction
Operator only. Creates the auction, reserves a 6 character join code, and returns links for the auctioneer console and the projector screen. The tokens are inside the links (fragment #token=), valid 12 hours.
Authentication
- adminKey (header X-Admin-Key)
Request body
application/json (required)
CreateAuctionRequest
| Field | Type | Description |
|---|---|---|
| title | string | Lot title shown to bidders.min length 1; max length 120; default "Untitled auction" |
| config (required) | AuctionConfig | Settings of one auction. Amounts are in cents, durations in milliseconds. |
| mode | string | Bidding mode. Defaults to english.one of "english", "proxy", "second_price"; default "english" |
| currency (required) | const "USD" | Currency of every amount. Only USD is accepted. |
| reserve (required) | integer | Reserve price in cents (at least 100).min 100 |
| minIncrement (required) | integer | Smallest raise in cents.min 1 |
| endTs (required) | EpochMs | Milliseconds since the Unix epoch. |
| softCloseWindowMs (required) | integer | A bid this close to the end extends the lot.min 0; max 600000 |
| softCloseExtensionMs (required) | integer | How long a soft close extends the lot, in milliseconds.min 0; max 600000 |
| maxExtensions (required) | integer | Most times the lot can be extended by soft close.min 0; max 50 |
| ceilingPresets (required) | array of integer | Strictly ascending ceiling amounts in cents, none below the reserve. |
| confirmConfidenceThreshold (required) | number | Spoken bids below this confidence need the bidder to confirm.min 0; max 1 |
| autoHammerDelayMs | integer | Milliseconds after closing begins before the host hammers the lot by itself. When absent, the auctioneer hammers by hand.min 0 |
| holdScope | string | Whether one hold covers the whole event or a single lot. The engine default is event.one of "event", "lot" |
| incrementLadder | array of object | Tiered increments. Must start at fromCents 0 and strictly ascend. |
| fromCents (required) | integer | Price in cents from which this increment applies.min 0 |
| incrementCents (required) | integer | Smallest raise in cents at this price tier.min 1 |
| fundraiserGoalCents | integer | Optional goal; the projector shows a thermometer only when it is set.min 1; max 100000000000 |
{
"title": "Charity quilt",
"config": {
"mode": "english",
"currency": "USD",
"reserve": 10000,
"minIncrement": 500,
"endTs": 1767225600000,
"softCloseWindowMs": 30000,
"softCloseExtensionMs": 30000,
"maxExtensions": 5,
"ceilingPresets": [
10000,
25000,
50000
],
"confirmConfidenceThreshold": 0.85
},
"fundraiserGoalCents": 500000
}Responses
201 Auction created.
application/json
CreateAuctionResponse
| Field | Type | Description |
|---|---|---|
| auctionId (required) | Ulid | 26 character id (Crockford base 32).pattern ^[0-9A-HJKMNP-TV-Z]{26}$ |
| joinCode (required) | JoinCode | Six letters and digits without look-alikes (no 0, O, 1, I, L).pattern ^[ABCDEFGHJKMNPQRSTUVWXYZ23456789]{6}$ |
| lotTitle (required) | string | Title of the lot, as given in the request. |
| auctioneerLink (required) | string (uri) | Link to the auctioneer console. The auctioneer token is in the URL fragment. |
| screenLink (required) | string (uri) | Link to the projector screen. The screen token is in the URL fragment. |
{
"auctionId": "01JC5ZP4M7Q8R9S0T1V2W3X4Y5",
"joinCode": "K7M2QX",
"lotTitle": "Charity quilt",
"auctioneerLink": "https://gavel-web.example/r/01JC5ZP4M7Q8R9S0T1V2W3X4Y5/console#token=AUCTIONEER_TOKEN",
"screenLink": "https://gavel-web.example/r/01JC5ZP4M7Q8R9S0T1V2W3X4Y5/screen#token=SCREEN_TOKEN"
}400 The body, query or path is not valid (`bad_message`). `detail` lists the failing fields.
application/json
{
"code": "bad_message",
"message": "invalid request body",
"detail": "config.reserve: reserve must be at least 100 cents"
}401 The credential is missing, expired, revoked, of the wrong kind or for another auction.
application/json
{
"code": "unauthorized",
"message": "access token required"
}413 The body is larger than 64 KiB (`bad_message`).
application/json
{
"code": "bad_message",
"message": "request body too large"
}415 A body was sent that is not `application/json` (`bad_message`).
application/json
{
"code": "bad_message",
"message": "content-type must be application/json"
}429 Too many requests (`rate_limited`), a locked-out source (`code_locked`, `judge_join_locked`), a full judge room (`judge_room_full`), or a judge-room cap or create limit. Wait `Retry-After` seconds.
application/json
{
"error": "rate_limited",
"message": "Too many tries. Wait a minute and try again."
}500 Something failed on the host (`internal`). The message never carries internals.
application/json
{
"code": "internal",
"message": "internal error"
}