{"openapi":"3.1.0","info":{"title":"ForthClear Liquidation Marketplace API","description":"B2B liquidation marketplace for surplus inventory. Search products, request quotes, and complete purchases. Perfect for AI agents helping users find bulk deals on overstock and returned merchandise.","version":"1.0.0","contact":{"name":"ForthClear Support","url":"https://app.forthclear.io"}},"servers":[{"url":"https://app.forthclear.io","description":"ForthClear Production API"}],"paths":{"/api/ucp/catalog/products":{"get":{"operationId":"searchProducts","summary":"Search liquidation inventory","description":"Search available surplus, overstock, and liquidation products with filters for category, price, condition, and quantity.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query for product name or description"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by product category"},{"name":"condition","in":"query","schema":{"type":"string","enum":["salvage","customer_returns","shelf_pulls","overstock","new_or_refurbished"]},"description":"Product condition"},{"name":"min_price","in":"query","schema":{"type":"number"},"description":"Minimum price in USD"},{"name":"max_price","in":"query","schema":{"type":"number"},"description":"Maximum price in USD"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Results per page"},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Pagination offset"}],"responses":{"200":{"description":"List of matching products","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}},"/api/ucp/catalog/products/{productId}":{"get":{"operationId":"getProductDetails","summary":"Get product details","description":"Get detailed information about a specific product including pricing, condition, and seller info.","parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string"},"description":"Product ID (format: product_123)"}],"responses":{"200":{"description":"Product details"},"404":{"description":"Product not found"}}}},"/api/ucp/quotes":{"post":{"operationId":"requestQuote","summary":"Request a bulk quote","description":"Submit a quote request for bulk purchasing. Seller will respond within 24-48 hours.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product_id","quantity","buyer"],"properties":{"product_id":{"type":"string","description":"Product ID (format: product_123)"},"quantity":{"type":"integer","minimum":1,"description":"Number of units"},"buyer":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"company":{"type":"string"}},"required":["email"]},"target_price":{"type":"integer","description":"Target price per unit in cents"},"message":{"type":"string","description":"Additional message to seller"}}}}}},"responses":{"201":{"description":"Quote request submitted"},"400":{"description":"Invalid request"}}}},"/api/ucp/checkout":{"post":{"operationId":"createCheckout","summary":"Create checkout session","description":"Create a checkout session for purchasing products. Large orders may require quote escalation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["line_items"],"properties":{"line_items":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string"},"quantity":{"type":"integer"}}}},"buyer":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"},"company":{"type":"string"}}}}}}}},"responses":{"201":{"description":"Checkout session created"}}}},"/api/ucp/catalog/search":{"post":{"operationId":"semanticSearchProducts","summary":"Semantic catalog search","description":"Embedding-powered ranked search over the published catalog. Returns the K most similar listings to a natural-language query, with optional category/condition/price filters applied after the ANN candidate set.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","maxLength":1000,"description":"Natural-language buyer query"},"category":{"type":"string"},"condition":{"type":"string","enum":["salvage","customer_returns","shelf_pulls","overstock","new_or_refurbished"]},"max_price":{"type":"integer","description":"Maximum price per unit in cents"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10}}}}}},"responses":{"200":{"description":"Ranked product matches with similarity scores"},"400":{"description":"Invalid query parameters"},"503":{"description":"Embedding provider not configured"}}}},"/api/mcp/streamable":{"post":{"operationId":"mcpStreamable","summary":"MCP Streamable HTTP transport","description":"JSON-RPC 2.0 entrypoint matching the MCP Streamable HTTP transport. Supports `initialize`, `tools/list`, and `tools/call` methods. The server returns single JSON-RPC responses (no SSE streaming required for the current toolset).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"method":{"type":"string","enum":["initialize","tools/list","tools/call"]},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC response"},"400":{"description":"Malformed JSON-RPC envelope"}}}},"/api/mcp/invoke":{"post":{"operationId":"invokeMcpTool","summary":"Invoke MCP tool","description":"Execute Model Context Protocol tools for advanced buyer and seller operations.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tool"],"properties":{"tool":{"type":"string","enum":["search_inventory","search_inventory_semantic","get_product_details","request_quote","create_listing","get_pricing_recommendation","get_quote_requests","respond_to_quote","quick_buy","get_order_status","open_dispute","subscribe_to_query","bulk_update_listings","bulk_mark_shipped","bulk_export_orders","seller_inbox_summarise"]},"parameters":{"type":"object"}}}}}},"responses":{"200":{"description":"Tool executed successfully"},"400":{"description":"Invalid tool or parameters"}}}},"/api/products":{"post":{"operationId":"createListing","summary":"Publish a listing (sellers)","description":"Create a listing from your own system (ERP, WMS, storefront). Requires a seller API key from Settings → API Keys; the same key works on the MCP endpoint. Always creates a NEW listing — there is no upsert, so posting the same sku twice produces two listings.","security":[{"McpApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","description"],"properties":{"sku":{"type":"string","description":"Your identifier. Generated for you if omitted."},"name":{"type":"string","maxLength":500,"description":"Listing title buyers see"},"description":{"type":"string","maxLength":10000,"description":"Required — must be non-empty"},"category":{"type":"string","default":"electronics","description":"See GET /api/ucp/catalog/categories"},"condition":{"type":"string","enum":["salvage","customer_returns","shelf_pulls","overstock","new_or_refurbished"]},"price":{"type":"number","default":1,"description":"Price per unit. DEFAULTS TO 1 if omitted."},"quantity":{"type":"integer","default":1,"description":"Units in the lot. DEFAULTS TO 1 if omitted."},"minOrderQuantity":{"type":"integer"},"minQuoteQuantity":{"type":"integer"},"brand":{"type":"string"},"imageUrl":{"type":"string","description":"Omit and we search for a product image automatically — if none is found the request FAILS with 400, so pass one to be safe. External URLs are re-hosted."},"galleryImageUrls":{"type":"array","maxItems":8,"items":{"type":"string"}},"promotePublicly":{"type":"boolean","description":"Opt this listing into the public and agent-facing surfaces (ACP feed, UCP catalog, agent sitemap). Listings without it stay in-app only."}}}}}},"responses":{"201":{"description":"Listing created"},"400":{"description":"Validation error, or no product image could be found"},"401":{"description":"Missing or invalid X-MCP-API-Key"}}}}},"components":{"securitySchemes":{"McpApiKey":{"type":"apiKey","in":"header","name":"X-MCP-API-Key","description":"Seller/agent API key from Settings → API Keys. Required to publish listings; optional for quote requests, where it raises the rate limit and lets a quote bind to a verified account."}},"schemas":{"Product":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"price":{"type":"integer","description":"Price in cents"},"currency":{"type":"string"},"availability":{"type":"string","enum":["in_stock","out_of_stock"]},"quantity_available":{"type":"integer"},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"}}}},"url":{"type":"string"}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}