API overview

The Bidvise Catalogue API reads your catalogue over HTTP: the auctions you are running, the sessions inside them, the lots on offer, the items behind those lots, and their images.

It is a small, predictable REST API (plural nouns, JSON out, standard HTTP semantics) with catalogue reads plus atomic item creation and updates.

https://app.bidvise.com/api/v2

All requests are authenticated with an API key, and the key determines which auction house you are reading. GET /api/v2 with a key returns what is here and where the documentation lives; anything under /api/v2 that does not exist answers with a problem document, never a web page.

The model

Five resources, one hierarchy:

Resource	What it is
`auctions`	The sale event a house announces: “Spring Auction 2026”
`sessions`	A sitting within an auction, with its own opening and closing: timed or live
`lots`	An item offered in a session, with its number, estimate and result
`items`	The physical object: title, description, condition, dimensions
`images`	The photographs of an item

An auction contains sessions; a session contains lots; a lot offers an item; an item has images. That is the core model. Sellers, consignments and the reference lists are described with the other resources.

The split between a lot and an item is the one piece worth internalising: the item is the object itself and outlives any sale, while the lot is that object offered in one session at one number. The same item can be relisted as a new lot.

Quickstart

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

{
  "data": [
    {
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Relationships come back as IDs. Ask for them inline when you want them:

curl "https://app.bidvise.com/api/v2/lots/lot_b48e0a19-5c72-4d83-91af-3e6b2c07d514?expand[]=item&expand[]=item.images" \
  -H "Authorization: Bearer $BIDVISE_API_KEY"

Principles

Prefixed IDs (auc_, ses_, lot_, itm_, img_): every ID says what it is, and the wrong kind is rejected rather than silently mishandled.
Money is exact: integer minor units plus an ISO 4217 currency, never floats.
Depth is a parameter: expand[], not a parallel set of “detailed” endpoints.
One envelope, one pagination, one error shape: cursor pagination everywhere, RFC 9457 problem documents for every error.
Nothing is serialised implicitly: every field is named in a serializer, so our database schema is never your contract.
Spec-backed: the OpenAPI 3.1 document is asserted against real responses in our test suite, so it cannot drift from the code.

Everything above is spelled out in conventions.

What is not here yet

This version covers the catalogue: auctions, sessions, lots, items and images, plus sellers, consignments and the reference lists. Bids, buyers, invoices, payments, registrations, settlements, direct-sale listings and webhooks are not available through the API.