{ "openapi": "3.1.0", "info": { "title": "Bidyear REST API", "version": "1.0.0", "description": "JSON REST API for the Bidyear land-auction marketplace platform.\n\nAll responses share a consistent envelope:\n```json\n{\"success\": true, \"data\": {...}, \"message\": \"...\"}\n```\n\nPaginated lists include a `meta` object with `current_page`, `last_page`, `per_page`, `total`.\n\n**Rate limit:** 60 requests/minute per authenticated user or IP address.\n\n**Token abilities:** Create Sanctum tokens at *Account → API Tokens*. Select the abilities your integration needs:\n- `read` – access own invoices, profile\n- `write` – place bids, manage watchlist and media\n- `seller` – ad campaigns, webhook subscriptions, current subscription\n- `admin` – reserved for platform administrators\n\nSPA / browser sessions with an active Sanctum session bypass token ability checks on media endpoints.", "contact": { "name": "Bidyear Platform", "url": "https://bidyear.com/contact" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "/api", "description": "Current domain (relative)" }, { "url": "https://bidyear.com/api", "description": "Production" } ], "security": [], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Sanctum personal access token (ability-scoped)", "description": "Obtain tokens at Account → API Tokens. Pass as `Authorization: Bearer {token}`." } }, "schemas": { "SuccessEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "OK" }, "data": {} }, "required": ["success", "data"] }, "ErrorEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "code": { "type": "string" } }, "required": ["success", "message"] }, "PaginatedMeta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } } }, "Auction": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": ["draft","active","closed","cancelled"] }, "starts_at": { "type": "string", "format": "date-time", "nullable": true }, "ends_at": { "type": "string", "format": "date-time", "nullable": true }, "lots_count": { "type": "integer" }, "auctioneer": { "$ref": "#/components/schemas/UserSummary" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Lot": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": ["active","sold","unsold","withdrawn"] }, "reserve_met": { "type": "boolean", "nullable": true, "description": "Null if reserve is hidden" }, "current_bid": { "type": "number", "format": "float", "nullable": true }, "bid_count": { "type": "integer" }, "acreage": { "type": "number", "format": "float", "nullable": true }, "county": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "zoning": { "type": "string", "nullable": true }, "parcel_id": { "type": "string", "nullable": true }, "lat": { "type": "number", "format": "float", "nullable": true }, "lng": { "type": "number", "format": "float", "nullable": true }, "auction_id": { "type": "integer" }, "category": { "$ref": "#/components/schemas/CategorySummary" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/Media" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "GeoJsonFeatureCollection": { "type": "object", "properties": { "type": { "type": "string", "enum": ["FeatureCollection"] }, "features": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["Feature"] }, "geometry": { "type": "object", "nullable": true }, "properties": { "type": "object", "properties": { "lot_id": { "type": "integer" }, "title": { "type": "string" }, "slug": { "type": "string" }, "current_bid": { "type": "number", "nullable": true }, "status": { "type": "string" }, "acreage": { "type": "number", "nullable": true } } } } } } } }, "Bid": { "type": "object", "properties": { "id": { "type": "integer" }, "amount": { "type": "number", "format": "float" }, "is_proxy": { "type": "boolean" }, "bidder": { "type": "string", "description": "Anonymised — e.g. 'Bidder #3'" }, "is_winning": { "type": "boolean" }, "placed_at": { "type": "string", "format": "date-time" } } }, "Category": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parent_id": { "type": "integer", "nullable": true }, "is_active": { "type": "boolean" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/CategorySummary" } } } }, "CategorySummary": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "Invoice": { "type": "object", "properties": { "id": { "type": "integer" }, "invoice_number": { "type": "string" }, "kind": { "type": "string", "enum": ["winner","platform_fee","subscription","deposit"] }, "status": { "type": "string", "enum": ["draft","open","paid","voided","refunded"] }, "amount_due": { "type": "number", "format": "float" }, "amount_paid": { "type": "number", "format": "float" }, "currency": { "type": "string", "example": "usd" }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "lot": { "$ref": "#/components/schemas/LotSummary" }, "created_at": { "type": "string", "format": "date-time" } } }, "LotSummary": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "slug": { "type": "string" } } }, "UserSummary": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "Me": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "email_verified_at": { "type": "string", "format": "date-time", "nullable": true }, "roles": { "type": "array", "items": { "type": "string" } }, "current_team_id": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "MeVerification": { "type": "object", "properties": { "identity_verified": { "type": "boolean" }, "phone_verified": { "type": "boolean" }, "seller_approved": { "type": "boolean" }, "tier": { "type": "string", "nullable": true }, "bid_limit": { "type": "number", "nullable": true }, "can_bid": { "type": "boolean" }, "next_step": { "type": "string", "nullable": true } } }, "AdCampaign": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string", "enum": ["draft","pending_payment","active","paused","ended","cancelled"] }, "placement": { "type": "string" }, "pricing_model": { "type": "string", "enum": ["flat","cpc","cpm"] }, "budget_cents": { "type": "integer", "nullable": true }, "spent_cents": { "type": "integer" }, "impressions": { "type": "integer" }, "clicks": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date", "nullable": true } } }, "SubscriptionPlan": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "price_monthly": { "type": "number" }, "price_yearly": { "type": "number", "nullable": true }, "features": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" } } }, "CrossListingPlatform": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logo_url": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } } }, "HelpCategory": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" } } }, "HelpArticle": { "type": "object", "properties": { "slug": { "type": "string" }, "category_slug": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "updated": { "type": "string", "format": "date" }, "url": { "type": "string" } } }, "WebhookSubscription": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/OutboundWebhookEvent" } }, "is_active": { "type": "boolean" }, "secret": { "type": "string", "description": "HMAC secret — shown only at creation time" }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "integer" }, "event": { "type": "string" }, "url": { "type": "string" }, "status_code": { "type": "integer", "nullable": true }, "success": { "type": "boolean" }, "response_body":{ "type": "string", "nullable": true }, "attempted_at": { "type": "string", "format": "date-time" }, "duration_ms": { "type": "integer", "nullable": true } } }, "OutboundWebhookEvent": { "type": "string", "enum": [ "lot.sold", "lot.unsold", "auction.published", "bid.placed", "invoice.paid", "invoice.payment_failed", "user.verified", "seller.approved", "subscription.updated" ], "description": "Available outbound webhook event names. Subscribe to any combination when creating a WebhookSubscription." }, "Media": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "thumb_url": { "type": "string", "format": "uri", "nullable": true }, "mime_type": { "type": "string" }, "file_name": { "type": "string" }, "order": { "type": "integer" } } }, "TokenAbility": { "type": "string", "enum": ["read", "write", "seller", "admin"], "description": "Sanctum token ability. `read` = invoices/profile/watchlist. `write` = bids/watchlist/media/verification uploads. `seller` = campaigns/webhooks/inventory/seller CRUD. `admin` = platform administrator." }, "InventoryItem": { "type": "object", "properties": { "id": { "type": "integer" }, "sku": { "type": "string", "nullable": true }, "title": { "type": "string" }, "status": { "type": "string", "enum": ["in_stock", "listed", "sold", "written_off"] }, "purchase_cost": { "type": "number" }, "lot_id": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Settlement": { "type": "object", "properties": { "id": { "type": "integer" }, "lot_id": { "type": "integer" }, "hammer_price": { "type": "number" }, "buyers_premium": { "type": "number" }, "seller_commission": { "type": "number" }, "platform_fee": { "type": "number" }, "net_proceeds": { "type": "number" }, "status": { "type": "string" }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "VerificationDocument": { "type": "object", "properties": { "id": { "type": "integer" }, "document_type": { "type": "string", "enum": ["government_id", "business_license", "w9", "ein_confirmation", "beneficial_ownership_attestation", "bank_letter", "proof_of_address"] }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } }, "paths": { "/v1/auctions": { "get": { "operationId": "listAuctions", "summary": "List public auctions", "tags": ["Auctions"], "description": "Returns a paginated list of active public auctions.", "parameters": [ { "name": "category_id", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string", "enum": ["starts_at","ends_at","title"] } }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": ["asc","desc"] } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Paginated list of auctions", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Auction" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } } ] } } } } } } }, "/v1/auctions/{auction}": { "get": { "operationId": "showAuction", "summary": "Auction detail", "tags": ["Auctions"], "parameters": [ { "name": "auction", "in": "path", "required": true, "description": "Auction ID or slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Auction", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/Auction" } } }] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/auctions/{auction}/lots": { "get": { "operationId": "listAuctionLots", "summary": "Lots in an auction", "tags": ["Auctions"], "parameters": [ { "name": "auction", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Paginated lots", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lot" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }] } } } } } } }, "/v1/lots": { "get": { "operationId": "listLots", "summary": "List active lots", "tags": ["Lots"], "parameters": [ { "name": "auction_id", "in": "query", "schema": { "type": "integer" } }, { "name": "category_id", "in": "query", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "schema": { "type": "string" } }, { "name": "acreage_min", "in": "query", "schema": { "type": "number" } }, { "name": "acreage_max", "in": "query", "schema": { "type": "number" } }, { "name": "county", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "zoning", "in": "query", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Paginated lots", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lot" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }] } } } } } } }, "/v1/lots/geojson": { "get": { "operationId": "lotsGeoJson", "summary": "GeoJSON FeatureCollection of land lots", "description": "Returns all active land lots with coordinates as a GeoJSON FeatureCollection for map rendering. Accepts the same filters as `GET /v1/lots`.", "tags": ["Lots"], "parameters": [ { "name": "county", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "zoning", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "GeoJSON FeatureCollection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeoJsonFeatureCollection" } } } } } } }, "/v1/lots/{lot}": { "get": { "operationId": "showLot", "summary": "Lot detail", "tags": ["Lots"], "parameters": [ { "name": "lot", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lot with images and land fields", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/Lot" } } }] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/lots/{lot}/bids": { "get": { "operationId": "listLotBids", "summary": "Bid history for a lot", "description": "Bidder identities are anonymised — shown as 'Bidder #N'. Proxy/max bid amounts are not exposed.", "tags": ["Bids"], "parameters": [ { "name": "lot", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Paginated bids", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Bid" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }] } } } } } }, "post": { "operationId": "placeBid", "summary": "Place a bid", "description": "Routes through ProxyBiddingService — identical verification, deposit, and proxy-war logic as the web UI. Requires `write` token ability.\n\nEnforces:\n- Lot/auction must be open for bidding\n- Bidder verification tier check\n- Bid deposit registration\n- Capability check\n- Row-level lock for concurrent bid protection\n- Proxy war logic (outbids proxy holders automatically)", "tags": ["Bids"], "security": [{ "bearerAuth": ["write"] }], "parameters": [ { "name": "lot", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["bid_amount"], "properties": { "bid_amount": { "type": "number", "format": "float", "description": "Bid amount in the auction's currency" }, "is_proxy": { "type": "boolean", "default": false, "description": "If true, registers as a max/proxy bid" } } } } } }, "responses": { "200": { "description": "Bid placed successfully", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/Bid" } } }] } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Token lacks `write` ability, or bidder verification/deposit check failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Validation error or bid too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/lots/{lot}/watchlist": { "post": { "operationId": "addWatchlist", "summary": "Add lot to watchlist", "tags": ["Bids"], "security": [{ "bearerAuth": ["write"] }], "parameters": [{ "name": "lot", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Added to watchlist" }, "401": { "description": "Unauthenticated" } } }, "delete": { "operationId": "removeWatchlist", "summary": "Remove lot from watchlist", "tags": ["Bids"], "security": [{ "bearerAuth": ["write"] }], "parameters": [{ "name": "lot", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Removed from watchlist" }, "401": { "description": "Unauthenticated" } } } }, "/v1/categories": { "get": { "operationId": "listCategories", "summary": "List categories", "tags": ["Categories"], "parameters": [ { "name": "tree", "in": "query", "schema": { "type": "boolean" }, "description": "Set to true to return nested tree with children" } ], "responses": { "200": { "description": "Category list or tree", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } }] } } } } } } }, "/v1/categories/{category}": { "get": { "operationId": "showCategory", "summary": "Category detail", "tags": ["Categories"], "parameters": [{ "name": "category", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Category", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/Category" } } }] } } } } } } }, "/v1/categories/{category}/children": { "get": { "operationId": "listCategoryChildren", "summary": "Child categories", "tags": ["Categories"], "parameters": [{ "name": "category", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Child categories", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CategorySummary" } } } }] } } } } } } }, "/v1/categories/{category}/schema": { "get": { "operationId": "getCategorySchema", "summary": "Dynamic form schema for a category", "description": "Returns the JSON form schema defining which additional fields apply to lots in this category (e.g. mineral rights, utilities, HOA for land categories).", "tags": ["Categories"], "parameters": [{ "name": "category", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Form schema array", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } } } } }, "/v1/subscription-plans": { "get": { "operationId": "listSubscriptionPlans", "summary": "List available subscription plans", "description": "Public endpoint — used on pricing and marketing pages.", "tags": ["Subscriptions"], "responses": { "200": { "description": "Plans", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionPlan" } } } }] } } } } } } }, "/v1/cross-listing-platforms": { "get": { "operationId": "listCrossListingPlatforms", "summary": "List cross-listing integration platforms", "description": "Public integration directory of platforms that can simulcast auctions.", "tags": ["Cross-listing"], "responses": { "200": { "description": "Platforms", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CrossListingPlatform" } } } }] } } } } } } }, "/v1/help/categories": { "get": { "operationId": "helpCategories", "summary": "Help center categories", "tags": ["Help"], "responses": { "200": { "description": "List of help categories visible to the caller", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HelpCategory" } } } }] } } } } } } }, "/v1/help/search": { "get": { "operationId": "helpSearch", "summary": "Search help articles", "tags": ["Help"], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Matching help articles with snippets", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/HelpArticle" } } } }] } } } } } } }, "/user": { "get": { "operationId": "apiUser", "summary": "Authenticated user (Jetstream compat)", "description": "Returns the authenticated user resource. Compatible with the Jetstream SPA default. See `GET /v1/me` for the full v1 resource format.", "tags": ["Me"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "User", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Unauthenticated" } } } }, "/v1/me": { "get": { "operationId": "showMe", "summary": "Authenticated user (v1 format)", "tags": ["Me"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "User resource", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/Me" } } }] } } } }, "401": { "description": "Unauthenticated" } } } }, "/v1/me/verification": { "get": { "operationId": "meVerification", "summary": "Verification and account status", "description": "Returns identity verification tier, phone verification, seller approval status, bid limit, and the next recommended action if verification is incomplete.", "tags": ["Me"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Verification status", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/MeVerification" } } }] } } } }, "401": { "description": "Unauthenticated" } } } }, "/v1/invoices": { "get": { "operationId": "listInvoices", "summary": "List your invoices", "description": "Returns the authenticated user's invoices (winner invoices, platform fees, subscriptions, deposits). Requires `read` token ability.", "tags": ["Invoices"], "security": [{ "bearerAuth": ["read"] }], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["draft","open","paid","voided","refunded"] } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": ["winner","platform_fee","subscription","deposit"] } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Paginated invoices", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Token lacks `read` ability" } } } }, "/v1/invoices/{id}": { "get": { "operationId": "showInvoice", "summary": "Invoice detail", "tags": ["Invoices"], "security": [{ "bearerAuth": ["read"] }], "parameters": [{ "name": "id", "in": "path", "required": true, "description": "Invoice ID or invoice number", "schema": { "type": "string" } }], "responses": { "200": { "description": "Invoice", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/Invoice" } } }] } } } }, "403": { "description": "Not your invoice" }, "404": { "description": "Not found" } } } }, "/v1/ad-campaigns": { "get": { "operationId": "listAdCampaigns", "summary": "List your ad campaigns", "description": "Returns campaigns owned by the authenticated user/team. Requires `seller` ability and `X-Team-Id` header for multi-team accounts.", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" }, "description": "Team context for multi-team sellers" }, { "name": "status", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated ad campaigns", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdCampaign" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Token lacks `seller` ability" } } }, "post": { "operationId": "createAdCampaign", "summary": "Create an ad campaign", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [{ "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "placement", "pricing_model", "start_date"], "properties": { "name": { "type": "string" }, "placement": { "type": "string" }, "pricing_model": { "type": "string", "enum": ["flat", "cpc", "cpm"] }, "budget_cents": { "type": "integer" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date", "nullable": true } } } } } }, "responses": { "201": { "description": "Campaign created" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "422": { "description": "Validation error" } } } }, "/v1/ad-campaigns/{adCampaign}": { "patch": { "operationId": "updateAdCampaign", "summary": "Update an ad campaign", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "adCampaign", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "budget_cents": { "type": "integer" }, "end_date": { "type": "string", "format": "date", "nullable": true } } } } } }, "responses": { "200": { "description": "Updated campaign" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" }, "404": { "description": "Not found" } } } }, "/v1/me/watchlist": { "get": { "operationId": "listMyWatchlist", "summary": "List watchlisted lots", "tags": ["Me"], "security": [{ "bearerAuth": ["read"] }], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Paginated watchlisted lots", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lot" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }] } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Token lacks `read` ability" } } } }, "/v1/me/verification/documents": { "get": { "operationId": "listVerificationDocuments", "summary": "List your verification documents", "tags": ["Me"], "security": [{ "bearerAuth": ["read"] }], "responses": { "200": { "description": "Document list", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VerificationDocument" } } } }] } } } }, "401": { "description": "Unauthenticated" } } }, "post": { "operationId": "uploadVerificationDocument", "summary": "Upload a verification document", "tags": ["Me"], "security": [{ "bearerAuth": ["write"] }], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["document_type", "file"], "properties": { "document_type": { "type": "string" }, "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "Document uploaded" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Token lacks `write` ability" }, "422": { "description": "Validation error" } } } }, "/v1/media": { "post": { "operationId": "uploadMedia", "summary": "Upload and attach media", "description": "Multipart upload attaching a file to a lot, auction, or inventory item you own. Requires `write` ability.", "tags": ["Media"], "security": [{ "bearerAuth": ["write"] }], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": ["file", "model_type", "model_id"], "properties": { "file": { "type": "string", "format": "binary" }, "model_type": { "type": "string", "enum": ["lot", "auction", "inventory_item"] }, "model_id": { "type": "integer" }, "collection": { "type": "string", "enum": ["images", "videos", "documents"] } } } } } }, "responses": { "201": { "description": "Media uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessEnvelope" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Not owner of target model" }, "404": { "description": "Model not found" } } } }, "/v1/seller/auctions": { "get": { "operationId": "listSellerAuctions", "summary": "List your auctions", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Paginated auctions" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } } }, "post": { "operationId": "createSellerAuction", "summary": "Create an auction", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [{ "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["title", "category_id", "start_time", "end_time"], "properties": { "title": { "type": "string" }, "category_id": { "type": "integer" }, "description": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" } } } } } }, "responses": { "201": { "description": "Auction created" }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } } } }, "/v1/seller/auctions/{auction}": { "get": { "operationId": "showSellerAuction", "summary": "Auction detail (seller)", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "auction", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Auction" }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } }, "patch": { "operationId": "updateSellerAuction", "summary": "Update an auction", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "auction", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Updated" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Forbidden" } } } }, "/v1/seller/lots": { "get": { "operationId": "listSellerLots", "summary": "List your lots", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } }, { "name": "auction_id", "in": "query", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Paginated lots" }, "401": { "description": "Unauthenticated" } } }, "post": { "operationId": "createSellerLot", "summary": "Create a lot", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [{ "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["auction_id", "title"], "properties": { "auction_id": { "type": "integer" }, "title": { "type": "string" }, "starting_bid": { "type": "number" }, "lot_number": { "type": "string" } } } } } }, "responses": { "201": { "description": "Lot created" }, "401": { "description": "Unauthenticated" } } } }, "/v1/seller/lots/{lot}": { "get": { "operationId": "showSellerLot", "summary": "Lot detail (seller)", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "lot", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lot" }, "401": { "description": "Unauthenticated" } } }, "patch": { "operationId": "updateSellerLot", "summary": "Update a lot", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "lot", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Updated" }, "401": { "description": "Unauthenticated" } } } }, "/v1/inventory": { "get": { "operationId": "listInventory", "summary": "List inventory items", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Paginated inventory", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InventoryItem" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }] } } } }, "401": { "description": "Unauthenticated" } } }, "post": { "operationId": "createInventoryItem", "summary": "Create inventory item", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [{ "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["title"], "properties": { "title": { "type": "string" }, "sku": { "type": "string" }, "purchase_cost": { "type": "number" }, "consignor_id": { "type": "integer", "nullable": true } } } } } }, "responses": { "201": { "description": "Created" }, "401": { "description": "Unauthenticated" } } } }, "/v1/inventory/aging-summary": { "get": { "operationId": "inventoryAgingSummary", "summary": "Inventory aging buckets", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [{ "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } }], "responses": { "200": { "description": "Aging bucket summary" }, "401": { "description": "Unauthenticated" } } } }, "/v1/inventory/convert-to-lots": { "post": { "operationId": "convertInventoryToLots", "summary": "Convert inventory items to lots", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [{ "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["auction_id", "inventory_item_ids"], "properties": { "auction_id": { "type": "integer" }, "inventory_item_ids": { "type": "array", "items": { "type": "integer" } } } } } } }, "responses": { "200": { "description": "Lots created" }, "401": { "description": "Unauthenticated" }, "422": { "description": "Validation error" } } } }, "/v1/inventory/{inventoryItem}": { "get": { "operationId": "showInventoryItem", "summary": "Inventory item detail", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "inventoryItem", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Inventory item" }, "401": { "description": "Unauthenticated" } } }, "patch": { "operationId": "updateInventoryItem", "summary": "Update inventory item", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "inventoryItem", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Updated" }, "401": { "description": "Unauthenticated" } } } }, "/v1/settlements": { "get": { "operationId": "listSettlements", "summary": "List seller settlements", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 15 } } ], "responses": { "200": { "description": "Paginated settlements", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Settlement" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }] } } } }, "401": { "description": "Unauthenticated" } } } }, "/v1/settlements/{settlement}": { "get": { "operationId": "showSettlement", "summary": "Settlement detail", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "settlement", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Settlement", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/Settlement" } } }] } } } }, "401": { "description": "Unauthenticated" }, "404": { "description": "Not found" } } } }, "/v1/subscriptions/current": { "get": { "operationId": "currentSubscription", "summary": "Current subscription", "description": "Returns the team's active subscription. Requires `seller` ability.", "tags": ["Seller"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Current subscription or null if none" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Token lacks `seller` ability" } } } }, "/v1/webhook-subscriptions": { "get": { "operationId": "listWebhookSubscriptions", "summary": "List webhook subscriptions", "tags": ["Webhooks"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [{ "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } }], "responses": { "200": { "description": "Your webhook subscriptions", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookSubscription" } } } }] } } } } } }, "post": { "operationId": "createWebhookSubscription", "summary": "Create a webhook subscription", "tags": ["Webhooks"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [{ "name": "X-Team-Id", "in": "header", "schema": { "type": "integer" } }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url", "events"], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/OutboundWebhookEvent" } }, "is_active": { "type": "boolean", "default": true } } } } } }, "responses": { "201": { "description": "Created — response includes `secret` field (shown once only)", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } }] } } } }, "422": { "description": "Validation error" } } } }, "/v1/webhook-subscriptions/{webhookSubscription}": { "get": { "operationId": "showWebhookSubscription", "summary": "Webhook subscription detail", "tags": ["Webhooks"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [{ "name": "webhookSubscription", "in": "path", "required": true, "schema": { "type": "integer" } }], "responses": { "200": { "description": "Subscription", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "$ref": "#/components/schemas/WebhookSubscription" } } }] } } } } } }, "patch": { "operationId": "updateWebhookSubscription", "summary": "Update a webhook subscription", "tags": ["Webhooks"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [{ "name": "webhookSubscription", "in": "path", "required": true, "schema": { "type": "integer" } }], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/OutboundWebhookEvent" } }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated subscription" } } }, "delete": { "operationId": "deleteWebhookSubscription", "summary": "Delete a webhook subscription", "tags": ["Webhooks"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [{ "name": "webhookSubscription", "in": "path", "required": true, "schema": { "type": "integer" } }], "responses": { "200": { "description": "Deleted" } } } }, "/v1/webhook-subscriptions/{webhookSubscription}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "Recent delivery log", "tags": ["Webhooks"], "security": [{ "bearerAuth": ["seller"] }], "parameters": [ { "name": "webhookSubscription", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Delivery log", "content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } }] } } } } } } }, "/media/reorder": { "post": { "operationId": "reorderMedia", "summary": "Reorder media attachments", "description": "Reorders media items attached to lots or auctions you own. Session-authenticated SPA users are also permitted without a token.", "tags": ["Media"], "security": [{ "bearerAuth": ["write"] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["media_ids"], "properties": { "media_ids": { "type": "array", "items": { "type": "integer" }, "description": "Ordered array of media IDs" } } } } } }, "responses": { "200": { "description": "Reordered" }, "403": { "description": "Media not owned by caller" } } } }, "/media/{media}": { "delete": { "operationId": "deleteMedia", "summary": "Delete a media item", "description": "Deletes a media item attached to a lot or auction you own. Admins can delete any media. Session-authenticated SPA users are also permitted.", "tags": ["Media"], "security": [{ "bearerAuth": ["write"] }], "parameters": [{ "name": "media", "in": "path", "required": true, "schema": { "type": "integer" } }], "responses": { "200": { "description": "Deleted" }, "403": { "description": "Media not owned by caller" }, "404": { "description": "Not found" } } } }, "/webhooks/stripe": { "post": { "operationId": "stripeWebhook", "summary": "Stripe inbound webhook", "description": "Receives Stripe webhook events (payment_intent.succeeded, invoice.paid, customer.subscription.*, etc.). Verified via `Stripe-Signature` header using the configured webhook secret. No Sanctum authentication.", "tags": ["Inbound Webhooks"], "security": [], "parameters": [ { "name": "Stripe-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "data": { "type": "object" } } } } } }, "responses": { "200": { "description": "Processed" }, "400": { "description": "Invalid signature" } } } }, "/webhooks/bid/{platform}": { "post": { "operationId": "incomingBidWebhook", "summary": "Incoming simulcast bid from external platform", "description": "Receives a bid event from a cross-listing platform (e.g. AuctionTime, Proxibid). HMAC-verified in the controller — no Sanctum.", "tags": ["Inbound Webhooks"], "security": [], "parameters": [ { "name": "platform", "in": "path", "required": true, "description": "Platform slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bid accepted" }, "401": { "description": "Invalid HMAC signature" }, "422": { "description": "Lot not found or auction closed" } } } }, "/webhooks/sold/{platform}": { "post": { "operationId": "incomingSoldWebhook", "summary": "Incoming sold/hammer event from external platform", "description": "Receives a lot-sold event from a cross-listing platform. HMAC-verified. No Sanctum.", "tags": ["Inbound Webhooks"], "security": [], "parameters": [ { "name": "platform", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sold event processed" }, "401": { "description": "Invalid HMAC signature" } } } } }, "tags": [ { "name": "Auctions", "description": "Public auction resources" }, { "name": "Lots", "description": "Public lot resources including GeoJSON" }, { "name": "Bids", "description": "Bid history (public) and bid placement (write ability)" }, { "name": "Categories", "description": "Browse taxonomy and dynamic form schemas" }, { "name": "Subscriptions", "description": "Public subscription plans listing" }, { "name": "Cross-listing", "description": "Integration platform directory" }, { "name": "Help", "description": "Help center categories and search" }, { "name": "Me", "description": "Authenticated user profile and verification status" }, { "name": "Invoices", "description": "Your invoices — requires read ability" }, { "name": "Seller", "description": "Ad campaigns, seller CRUD, inventory, settlements — requires seller ability" }, { "name": "Webhooks", "description": "Outbound webhook subscription CRUD and deliveries — requires seller ability" }, { "name": "Media", "description": "Media upload, reorder and delete — requires write ability" }, { "name": "Inbound Webhooks", "description": "Receive events from Stripe and cross-listing simulcast platforms. HMAC-verified, no Sanctum." } ] }