Bidyear REST API

Versioned JSON API for auctions, lots, bids, invoices, webhooks, and more. Version 1.0.

Base URL

https://bidyear.com/api

Local development:

http://127.0.0.1:PORT/api (use your local artisan port)

The OpenAPI 3.1 specification is available at /docs/api/openapi.json — import it into Postman, Insomnia, or any OpenAPI-compatible tool.

Response envelope

All V1 endpoints return a consistent JSON structure:

{
  "success": true,
  "data": { ... },
  "message": "Optional human-readable message"
}

Paginated lists include a meta object:

{
  "success": true,
  "data": [ ... ],
  "meta": { "current_page": 1, "last_page": 4, "per_page": 15, "total": 56 }
}

Errors use success: false with an errors map and a machine-readable code.

Quick start

List active public auctions:

curl "https://bidyear.com/api/v1/auctions?per_page=10"

GeoJSON land map:

curl "https://bidyear.com/api/v1/lots/geojson?state=TX"

Public vs authenticated: Most read endpoints are public. Bid placement, invoices, and seller features require a Sanctum token with the appropriate ability. See Authentication.

Full endpoint index

Method	Path	Auth	Description
PUBLIC — no authentication required
GET	/v1/auctions	—	List active public auctions
GET	/v1/auctions/{id\|slug}	—	Auction detail
GET	/v1/auctions/{id}/lots	—	Lots in an auction
GET	/v1/lots	—	List active lots (land filters: acreage, county, state, zoning)
GET	/v1/lots/geojson	—	GeoJSON FeatureCollection for map rendering
GET	/v1/lots/{id}	—	Lot detail with images and land fields
GET	/v1/lots/{id}/bids	—	Bid history (bidder identities anonymised)
GET	/v1/categories	—	Category list; `?tree=true` for nested hierarchy
GET	/v1/categories/{id}	—	Category detail
GET	/v1/categories/{id}/children	—	Child categories
GET	/v1/categories/{id}/schema	—	Dynamic field schema for a category
GET	/v1/subscription-plans	—	Available subscription plans
GET	/v1/cross-listing-platforms	—	Integration platform directory
GET	/v1/help/categories	—	Help center categories
GET	/v1/help/search?q=	—	Help article search
AUTHENTICATED — Sanctum bearer token required
GET	/user	Any	Authenticated user (Jetstream compat)
GET	/v1/me	Any	Authenticated user (v1 resource format)
GET	/v1/me/verification	Any	Verification tier and account status
GET	/v1/invoices	read	Your invoices (paginated)
GET	/v1/invoices/{id}	read	Invoice detail
POST	/v1/lots/{id}/bids	write	Place a bid via ProxyBiddingService
POST	/v1/lots/{id}/watchlist	write	Add to watchlist
DELETE	/v1/lots/{id}/watchlist	write	Remove from watchlist
GET	/v1/ad-campaigns	seller	Your ad campaigns
GET	/v1/subscriptions/current	seller	Current subscription
GET	/v1/webhook-subscriptions	seller	List webhook subscriptions
POST	/v1/webhook-subscriptions	seller	Create subscription
GET	/v1/webhook-subscriptions/{id}	seller	Subscription detail
PATCH	/v1/webhook-subscriptions/{id}	seller	Update subscription
DELETE	/v1/webhook-subscriptions/{id}	seller	Delete subscription
GET	/v1/webhook-subscriptions/{id}/deliveries	seller	Delivery log
POST	/media/reorder	write	Reorder media (or SPA session)
DELETE	/media/{id}	write	Delete media you own
INBOUND WEBHOOKS — HMAC verified, no Sanctum
POST	/webhooks/stripe	Stripe-Signature	Stripe inbound events
POST	/webhooks/bid/{platform}	HMAC	Incoming simulcast bid from platform
POST	/webhooks/sold/{platform}	HMAC	Incoming sold/hammer event from platform

Rate limiting

60 requests per minute per authenticated user or IP address (throttle:api). Exceeded requests return HTTP 429 Too Many Requests.