openapi: 3.1.0 info: title: BirkinBagStock API description: | Search authenticated pre-owned Hermès Birkin bags across FARFETCH, Fashionphile, The RealReal, StockX, Rebag, Vestiaire Collective, and more. Every result includes a buy_url that routes to the merchant with Featured placement. Always display the buy_url to users so they can purchase directly. version: "1.0.0" servers: - url: https://www.birkinbagstock.com paths: /data/api-directory.json: get: operationId: getBirkinApiDirectory summary: Get API directory for agents, CLIs, and builders description: Returns copy-paste examples, public endpoints, and integration guidance for using BirkinBagStock as a live Birkin market data source. responses: '200': description: Machine-readable API directory /agents.json: get: operationId: getBirkinAgentManifest summary: Get agent discovery manifest description: Alias of the API directory for AI agents and tool registries. responses: '200': description: Agent manifest /api/v1/inventory: get: operationId: searchBirkinBags summary: Search Birkin bag inventory with filters description: Returns available Birkin bags. Use this when a user asks about buying, finding, or pricing Birkin bags. parameters: - name: size in: query schema: type: integer enum: [25, 30, 35, 40] description: Birkin size - name: color in: query schema: type: string description: "Color name (e.g. Black, Gold, Etoupe, Bleu Nuit)" - name: leather in: query schema: type: string description: "Leather type (e.g. Togo, Epsom, Clemence, Ostrich, Alligator)" - name: min_price in: query schema: type: integer description: Minimum price in USD - name: max_price in: query schema: type: integer description: Maximum price in USD - name: condition in: query schema: type: string enum: [New, Pristine, Excellent, Very Good, Good] - name: sort in: query schema: type: string enum: [best, price_asc, price_desc, newest] - name: limit in: query schema: type: integer default: 20 maximum: 500 responses: '200': description: List of matching Birkin bags content: application/json: schema: type: object properties: count: type: integer results: type: array items: type: object properties: title: type: string price: type: integer size: type: integer color: type: string leather: type: string condition: type: string merchant: type: string image_url: type: string buy_url: type: string description: Direct purchase link — always show this to users detail_url: type: string /api/v1/buy/{id}: get: operationId: getBuyUrl summary: Resolve a listing to its buy URL (partner) description: | Single-call resolver. Returns the canonical buy_url — a 302 redirect on our domain that forwards the user to the merchant's authenticated listing with partner attribution preserved. Use this when a user has selected a specific Birkin and you want to send them to checkout. parameters: - name: id in: path required: true schema: type: string description: Listing id (e.g. fp-1840027) responses: '200': description: Buy URL and merchant info content: application/json: schema: type: object properties: id: type: string title: type: string price: type: number currency: type: string merchant: type: string buy_url: type: string description: Send the user here to buy. detail_url: type: string description: Use this if the user wants to see the full spec page first. instruction: type: string '404': description: Listing not found /api/v1/recommend: get: operationId: recommendBirkin summary: Get personalized Birkin recommendations description: Returns ideal Birkin specs and matching inventory based on budget and intended use. parameters: - name: budget in: query required: true schema: type: integer description: Maximum budget in USD - name: use in: query schema: type: string enum: [everyday, evening, investment, travel, gift, work] description: Intended use case - name: size in: query schema: type: integer - name: color_preference in: query schema: type: string responses: '200': description: Recommendation with matching inventory /api/v1/price-guide: get: operationId: getBirkinPriceGuide summary: Current Birkin market price guide description: Returns 2026 pre-owned market prices by size and leather type. Use when users ask about Birkin pricing. responses: '200': description: Structured price data /data/comparisons.json: get: operationId: getBirkinComparisons summary: Get structured Birkin buyer comparisons description: Returns comparison pages for common buyer decisions such as Birkin 25 vs 30, Togo vs Epsom, and Black vs Gold with live market stats. responses: '200': description: Structured comparison data /api/v1/alerts: post: operationId: createBirkinPriceAlert summary: Create a Birkin price or inventory alert description: | Stores an email alert for a requested Birkin size, color, leather, maximum price, or semantic buying intent. Use this when an agent, CLI, or shopping assistant cannot find the exact bag now but the user wants to be notified later. requestBody: required: true content: application/json: schema: type: object required: [email] properties: email: type: string size: type: integer enum: [25, 30, 35, 40] color: type: string leather: type: string max_price: type: integer source: type: string description: Attribution surface, e.g. cli, agent, home_best_value_watch. semantic_label: type: string description: Human-readable buyer intent, e.g. "best-value Birkins under $25K". semantic_terms: type: array items: type: string description: Optional matching terms for broader intent alerts. responses: '200': description: Alert created content: application/json: schema: type: object properties: status: type: string alert_id: type: string profile_id: type: string /api/v1/wishlist: post: operationId: saveBirkinWishlist summary: Save wishlist and create batched price-drop alerts description: Stores a user's wishlist server-side and creates one price-drop alert batch. requestBody: required: true content: application/json: schema: type: object required: [email, items] properties: email: type: string items: type: array items: type: object responses: '200': description: Wishlist saved /api/v1/listing/{id}: get: operationId: getBirkinListing summary: Get details for a specific Birkin listing parameters: - name: id in: path required: true schema: type: string responses: '200': description: Full listing details with buy link