{
    "openapi": "3.0.3",
    "info": {
        "title": "ShedBid Connect",
        "version": "1.0",
        "description": "Post buildings and run auctions on shedbid.com straight from your CRM or inventory system. Human docs: https://shedbid.com/developers"
    },
    "servers": [
        {
            "url": "https://shedbid.com/api/v1"
        }
    ],
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "sbk_live_..."
            }
        },
        "schemas": {
            "ListingInput": {
                "type": "object",
                "required": [
                    "building_type",
                    "starting_price"
                ],
                "properties": {
                    "external_id": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "Your SKU/stock number. Posting the same external_id again UPDATES that listing (safe to sync your whole inventory nightly)."
                    },
                    "building_type": {
                        "type": "string",
                        "example": "Lofted Barn"
                    },
                    "width": {
                        "type": "number",
                        "description": "Feet. Or pass size like \"12x24\"."
                    },
                    "length": {
                        "type": "number"
                    },
                    "height": {
                        "type": "number"
                    },
                    "size": {
                        "type": "string",
                        "example": "12x24",
                        "description": "Alternative to width/length."
                    },
                    "condition": {
                        "type": "string",
                        "enum": [
                            "new",
                            "repo"
                        ]
                    },
                    "description": {
                        "type": "string",
                        "maxLength": 5000
                    },
                    "starting_price": {
                        "type": "number",
                        "example": 4500
                    },
                    "reserve_price": {
                        "type": "number",
                        "description": "Hidden floor; never shown to bidders."
                    },
                    "buy_it_now": {
                        "type": "number"
                    },
                    "min_increment": {
                        "type": "number",
                        "description": "Defaults to a sane tier for the price."
                    },
                    "auction_days": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 30,
                        "default": 7
                    },
                    "end_time": {
                        "type": "string",
                        "description": "Explicit ISO end (max 60 days out); overrides auction_days."
                    },
                    "lot_id": {
                        "type": "integer",
                        "description": "One of GET /lots. The lot's address becomes the listing location."
                    },
                    "lot": {
                        "type": "string",
                        "description": "Lot name (alternative to lot_id)."
                    },
                    "zip": {
                        "type": "string",
                        "description": "Listing location when not on a lot."
                    },
                    "delivery_radius_miles": {
                        "type": "integer",
                        "description": "How far you will deliver; buyers outside it cannot bid."
                    },
                    "photo_urls": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "maxItems": 8,
                        "description": "Public image URLs; fetched, validated, and resized server-side."
                    },
                    "rto_terms": {
                        "type": "object",
                        "properties": {
                            "available": {
                                "type": "boolean"
                            },
                            "down_payment": {
                                "type": "number"
                            },
                            "monthly_payment": {
                                "type": "number"
                            },
                            "term_months": {
                                "type": "integer"
                            },
                            "notes": {
                                "type": "string"
                            }
                        }
                    },
                    "fulfillment_method": {
                        "type": "string",
                        "enum": [
                            "in_house",
                            "driver_auction",
                            "onsite_build"
                        ]
                    },
                    "relist": {
                        "type": "boolean",
                        "description": "When the external_id's previous auction already ended, create a fresh auction for it."
                    }
                }
            }
        }
    },
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/ping": {
            "get": {
                "summary": "Verify your API key",
                "responses": {
                    "200": {
                        "description": "Key is valid"
                    }
                }
            }
        },
        "/lots": {
            "get": {
                "summary": "Your active sale lots",
                "responses": {
                    "200": {
                        "description": "Lot list"
                    }
                }
            }
        },
        "/listings": {
            "get": {
                "summary": "Your listings",
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "external_id",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Listing array"
                    }
                }
            },
            "post": {
                "summary": "Create a listing (or update by external_id)",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ListingInput"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created"
                    },
                    "200": {
                        "description": "Updated via external_id"
                    },
                    "422": {
                        "description": "Validation errors"
                    }
                }
            }
        },
        "/listings/{id}": {
            "get": {
                "summary": "One listing incl. bid history",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Numeric id or SLID"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Listing"
                    }
                }
            },
            "patch": {
                "summary": "Update fields (reserve can't be raised once bids exist)",
                "responses": {
                    "200": {
                        "description": "Updated"
                    }
                }
            }
        },
        "/listings/{id}/end": {
            "post": {
                "summary": "Withdraw an active listing (only while it has no bids)",
                "responses": {
                    "200": {
                        "description": "Ended"
                    }
                }
            }
        },
        "/import": {
            "post": {
                "summary": "Bulk import: JSON array or CSV body (max 500 rows)",
                "responses": {
                    "200": {
                        "description": "Per-row report"
                    }
                }
            }
        },
        "/events": {
            "get": {
                "summary": "Poll auction events (bid/sold/ended) since an id - pull alternative to webhooks",
                "parameters": [
                    {
                        "name": "since_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Event list"
                    }
                }
            }
        }
    }
}