Skip to main content

API Reference

This reference documents major AuctioHub API contracts. Confirm final route paths from implementation before external publication.

Contract Format​

For each endpoint include:

  • Method and path
  • Auth requirement
  • Request schema
  • Response schema
  • Error responses
  • Side effects

Auth APIs​

Session Resolve​

  • Method and path: GET /api/auth/session
  • Auth requirement: optional
  • Request schema: none
  • Response schema: user session payload or null session
  • Error responses: 500 internal error
  • Side effects: none

Product And Bidding APIs​

Create Product With Auction Options​

  • Method and path: POST /api/products
  • Auth requirement: signed-in user
  • Request schema: product fields plus auction settings
  • Response schema: created product and auction metadata
  • Error responses: 400 validation, 401 unauthorized, 403 forbidden
  • Side effects: inserts product and auction records, emits notification event

Place Bid​

  • Method and path: POST /api/auctions/{auctionId}/bids
  • Auth requirement: signed-in user
  • Request schema: { "amount": number }
  • Response schema: accepted bid and updated current amount context
  • Error responses: 400 invalid amount, 403 banned user, 409 closed auction
  • Side effects: creates bid record, recomputes winner snapshot, emits event

Validation notes:

  • Amount must be greater than current amount.
  • Ban checks are enforced server-side.

Auction Session APIs​

Fetch Auction Session State​

  • Method and path: GET /api/auctions/{auctionId}/session
  • Auth requirement: optional or signed-in based on policy
  • Request schema: path parameter auctionId
  • Response schema: auction status, timer, current amount, winner snapshot
  • Error responses: 404 not found, 410 ended session
  • Side effects: none

Chat APIs​

Poll Chat Messages​

  • Method and path: GET /api/auctions/{auctionId}/chat?since=<cursor>
  • Auth requirement: signed-in participant
  • Request schema: optional cursor/timestamp query
  • Response schema: ordered message list and next cursor
  • Error responses: 401 unauthorized, 403 forbidden, 404 auction not found
  • Side effects: none

Send Chat Message​

  • Method and path: POST /api/auctions/{auctionId}/chat
  • Auth requirement: signed-in participant
  • Request schema: { "message": string }
  • Response schema: persisted message payload
  • Error responses: 400 invalid message, 403 forbidden
  • Side effects: creates chat message and optional notification event

Payment APIs​

Start Winner Checkout​

  • Method and path: POST /api/payments/checkout
  • Auth requirement: signed-in winner
  • Request schema: auction reference and return URLs
  • Response schema: checkout session URL or token
  • Error responses: 403 non-winner access, 409 invalid auction state
  • Side effects: creates checkout attempt record

Complete Payment​

  • Method and path: POST /api/payments/complete
  • Auth requirement: signed-in winner or trusted webhook path
  • Request schema: payment session reference
  • Response schema: final payment status
  • Error responses: 400 invalid payload, 409 state conflict
  • Side effects: marks paid/penalty outcome and finalizes auction idempotently

Idempotency note:

  • Repeated completion calls should return consistent final state without double-processing.

User Profile And Dashboard APIs​

Fetch Dashboard Summary​

  • Method and path: GET /api/dashboard
  • Auth requirement: signed-in user
  • Request schema: optional pagination filters
  • Response schema: activity summary, bids, outcomes, notifications
  • Error responses: 401 unauthorized
  • Side effects: none

Admin APIs​

List Users​

  • Method and path: GET /api/admin/users
  • Auth requirement: admin
  • Request schema: optional query filters
  • Response schema: paginated user list and role metadata
  • Error responses: 401 unauthorized, 403 forbidden
  • Side effects: none

Update User Role​

  • Method and path: PATCH /api/admin/users/{userId}/role
  • Auth requirement: admin
  • Request schema: { "role": "user" | "admin" }
  • Response schema: updated user record
  • Error responses: 400 invalid role, 403 forbidden, 404 not found
  • Side effects: role update audit event

Moderate Auction Participant​

  • Method and path: POST /api/admin/auctions/{auctionId}/ban
  • Auth requirement: admin
  • Request schema: participant id and reason
  • Response schema: moderation action result
  • Error responses: 400 invalid request, 404 target not found
  • Side effects: creates ban record, triggers winner recomputation when required

Notification APIs​

Fetch Notification Stream​

  • Method and path: GET /api/notifications
  • Auth requirement: signed-in user
  • Request schema: optional cursor and unread filter
  • Response schema: notification event list
  • Error responses: 401 unauthorized
  • Side effects: optional read markers when configured

Update User​

PATCH /api/admin/user/:id