Auctions & sessions

An auction is the sale event: the thing on the poster. A session is a sitting within that event with its own opening and closing: a timed session closing online on Sunday, a live session called in the room on Tuesday. One auction, any mix of sessions.

The auction object

{
  "id": "auc_3f2a1c04-9b7e-4d51-8a63-1e5c7d90b482",
  "title": "Spring Auction 2026",
  "description": "Furniture, art and curiosities.",
  "slug": "spring-auction-2026",
  "published": true,
  "opens_at": "2026-07-01T10:00:00Z",
  "sessions": ["ses_7c1d5e88-2a34-4f19-9b0c-6d2e8f4a1357", "ses_a5b30f27-6d18-4e92-8c47-2f9a1b6e3d08"],
  "created_at": "2026-05-12T09:30:00Z",
  "updated_at": "2026-05-30T11:02:00Z"
}

published is whether the auction appears on the house’s own website. On a session it means genuinely visible to a visitor: a session that is published but hidden reports false, and the published filter agrees. opens_at is the earliest opening across its sessions: a convenience, so you can sort a list of auctions by when bidding starts without expanding every one of them.

sessions is a list of IDs in sale order, or full objects with expand[]=sessions.

The session object

{
  "id": "ses_7c1d5e88-2a34-4f19-9b0c-6d2e8f4a1357",
  "title": "Day 1 - Art",
  "kind": "timed",
  "opens_at": "2026-06-20T10:00:00Z",
  "timed": {
    "first_lot_closes_at": "2026-07-05T19:00:00Z",
    "group_size": 5,
    "interval_seconds": 30,
    "extension_threshold_seconds": 120,
    "extension_seconds": 120
  },
  "live": null,
  "published": true,
  "finished": false,
  "auction": "auc_3f2a1c04-9b7e-4d51-8a63-1e5c7d90b482",
  "created_at": "2026-05-12T09:31:00Z",
  "updated_at": "2026-06-20T10:00:03Z"
}

kind is timed or live, and it decides which of the two schedules is present: a timed session carries timed and a null live, a live session the reverse. A schedule that does not apply is absent rather than borrowed from the other rule.

timed.first_lot_closes_at is when the closing sequence begins, not when the session ends. Lots close in groups of group_size, interval_seconds apart, and the session is over when its last lot is. extension_threshold_seconds and extension_seconds are the soft-close window: a bid that close to a lot’s end extends it by that much. They are what a bid actually does, defaults applied, and never null. live.online_bidding_closes_at is when online bidding shuts for the room sale.

finished says the session has run its course, which is distinct from any of those times having passed, because soft-close extensions move the real end.

auction is an ID, or the full object with expand[]=auction.

Endpoints

All four require the auctions.read permission. A session is an auction’s sitting, so it is governed by the same permission as the auction itself.

GET /auctions
GET /auctions/{id}
GET /sessions
GET /sessions/{id}

Lists take limit and cursor (pagination), plus:

Examples

Everything currently announced:

curl "https://app.bidvise.com/api/v2/auctions?published=true" \
  -H "Authorization: Bearer $BIDVISE_API_KEY"

One auction with its sittings inline, in a single request:

curl "https://app.bidvise.com/api/v2/auctions/auc_3f2a1c04-9b7e-4d51-8a63-1e5c7d90b482?expand[]=sessions" \
  -H "Authorization: Bearer $BIDVISE_API_KEY"

The sessions of one auction as their own paginated list: the better choice when an auction has many:

curl "https://app.bidvise.com/api/v2/sessions?auction=auc_3f2a1c04-9b7e-4d51-8a63-1e5c7d90b482" \
  -H "Authorization: Bearer $BIDVISE_API_KEY"

From here, lots & items are what a session actually offers.

Correct an empty draft

PATCH /sessions/{id} requires auctions.write and auctions.read. Supply title, settings, or both. The session must be unpublished, unfinished and have no current or archived lots; otherwise the API returns 409. A published-but-hidden session does not qualify.

{
  "title": "Session I: silver",
  "settings": {
    "buyer_premium_percentage": "28.50",
    "allow_proxy_bidding": false,
    "show_lot_numbers": true,
    "live_written_bids_compete": true
  }
}

Only supplied fields change. The title uses the house’s default language; other translations remain intact. The premium accepts 0–100 with at most two decimal places, as a JSON number or decimal string. Boolean settings require actual JSON booleans. Unknown fields and invalid values return 422 without saving any part of the request. Repeating values or sending { "settings": {} } makes no change.

Session kind, parent, import reference, publication and customer-bidding controls cannot be changed here. Timed sessions always let written bids compete; live_written_bids_compete controls live sessions only. Confirm settings before adding lots. The same settings are accepted when creating a draft with POST /sessions.

Replace draft timing

Before adding lots, the same PATCH can replace the schedule. Send opens_at and the complete block for the existing session kind, optionally alongside title and settings:

{
  "opens_at": "2026-09-20T09:00:00+02:00",
  "timed": {
    "first_lot_closes_at": "2026-09-21T19:00:00+02:00",
    "group_size": 2,
    "interval_seconds": 30
  }
}

For a live session, replace timed with live, containing both online_bidding_closes_at and live_bidding_starts_at. All dates need explicit offsets; closing and live start must follow opening, and online closing cannot follow live start. Timed group size and interval are positive integers. Optional extension_threshold_seconds and extension_seconds are nonnegative integers; omitting them preserves their current effective values.

Timing is a complete replacement: sending only an opening date or only one nested time returns 422. Sending the wrong kind’s block, both blocks, or null also returns 422. Omitting all timing fields preserves the schedule. Repeating the same schedule makes no change. Existing, archived or active lots make the session ineligible (409); this cannot move the closing times of a populated session.