GET /v3/auctions/:id — auction detail

GET

/v3/auctions/{auctionId}

const url = 'https://api-ha-prod-p8.handbid.dev/v3/auctions/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api-ha-prod-p8.handbid.dev/v3/auctions/example \
  --header 'Authorization: Bearer <token>'

NEW (HAN-1583, 2026-05-18). Auction-detail screen payload — strict superset of the AuctionCardSerializer card shape plus detail-only fields. Replaces V2 auction/view for the iOS card-tap → detail flow.

Auth: OPTIONAL. Bearer token flips isFavorite per the caller’s user_favorite_auction_relation row. Missing/invalid token degrades silently to anonymous (same opportunistic pattern as /v3/auction/:id/items).

Card-superset fields (identical wire shape to /v3/auctions rows): id, name, organizationName, status, isFeatured, itemCount, startTime, endTime, timeZone, streamStatus, latitude, longitude, currency, imageUrl, organizationImageUrl, featuredItems[], backgroundGradient (only when set).

Detail-only fields:

description — full text (legacy WYSIWYG may emit HTML).
vanityAddress — share-URL key, nullable.
appealsColor — theme accent hex.
address: { street1, street2, city, province{id,name,code}, postalCode, country{id,name,code} } — null when no address set; province/country sub-objects null when their FK is null.
organization: { id, name, description, website, logoUrl }.
stream: { status, url, startTime, endTime } — OMITTED entirely when streamStatus == 'off'.
donations: { allowPledge, enableCustom, enableMinimum, minimumAmount, enableOffline, offlineUpdatesThermometer, enableDouble, bigDonationThreshold, description, imageUrl, tax, levels[] } — minimumAmount and bigDonationThreshold nulled when their enable flag is 0. tax is a decimal string. levels[] items have {id, amount} only (no label).
tickets: { enabled, showInItems, goal, requireToRegister, requireForOwners, requireToBid } — goal is a decimal string.
checkout: { requireAddress }.
isFavorite — AUTHED ONLY. Key OMITTED on anonymous requests (matches existing card behavior).

Errors:

400 when :id is non-positive.
404 not_found for missing, test, deleted-events-org, status-outside-visible-set, or privacy-blocked auctions. Privacy gate is 1:1 identical to /v3/auction/:id/items (same precedence as loadAuctionForItems).

Cache: per-user key v3:auction:{id}:detail:{userId|anon}, 30s TTL, tagged on V3CacheTags::auction($id) + V3CacheTags::userFavorites($userId) when authed.

Authorizations

bearer

Parameters

Path Parameters

auctionId

required

string

Responses

200

Successful response

application/json