{"openapi":"3.1.0","info":{"title":"Erches Agent API","description":"API for AI agents to search, research, bid, and buy on the Erches European marketplace. Supports auctions, fixed-price items, and second-hand listings with AI-powered deep research.","version":"1.0.0","contact":{"email":"api@erches.com","url":"https://www.erches.com/agent"},"x-logo":{"url":"https://www.erches.com/logo.png"}},"servers":[{"url":"https://www.erches.com","description":"Production"},{"url":"http://localhost:3000","description":"Development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key. Get one at https://www.erches.com/agent. Demo key: erches_agent_public_test"}},"schemas":{"AgentResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"cached":{"type":"boolean"},"credits_remaining":{"type":"number"},"request_id":{"type":"string"}}}}},"SearchResult":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string","example":"EUR"},"type":{"type":"string","enum":["marketplace","auction"]},"condition":{"type":"string"},"category":{"type":"string"},"image_url":{"type":"string"},"seller":{"type":"object","properties":{"name":{"type":"string"},"rating":{"type":"number"},"country":{"type":"string"}}},"url":{"type":"string"}}},"ListingDetail":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"type":{"type":"string","enum":["marketplace","auction"]},"price":{"type":"number"},"currency":{"type":"string"},"condition":{"type":"string"},"category":{"type":"string"},"images":{"type":"array","items":{"type":"string"}},"specifications":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"}}}},"seller":{"type":"object"},"price_breakdown":{"type":"object","properties":{"item_price":{"type":"number"},"commission":{"type":"number"},"vat":{"type":"number"},"total":{"type":"number"},"seller_receives":{"type":"number"}}}}}}},"paths":{"/api/agent/search":{"get":{"operationId":"searchListings","summary":"Search listings","description":"Search across marketplace and auction listings. No auth required, but authenticated requests get higher rate limits.","tags":["Search"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Category filter (e.g., \"elektronica\", \"voertuigen\")"},{"name":"type","in":"query","schema":{"type":"string","enum":["marketplace","auction","all"],"default":"all"}},{"name":"minPrice","in":"query","schema":{"type":"number"},"description":"Minimum price in EUR"},{"name":"maxPrice","in":"query","schema":{"type":"number"},"description":"Maximum price in EUR"},{"name":"condition","in":"query","schema":{"type":"string","enum":["new","like_new","good","fair","for_parts"]}},{"name":"country","in":"query","schema":{"type":"string"},"description":"ISO 3166-1 alpha-2 country code"},{"name":"sort","in":"query","schema":{"type":"string","enum":["price_asc","price_desc","recent","popular","ending_soon"],"default":"recent"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"429":{"description":"Rate limit exceeded"}},"x-curl-example":"curl 'http://localhost:3000/api/agent/search?q=iphone&type=marketplace&maxPrice=500'"}},"/api/agent/listings/{id}":{"get":{"operationId":"getListing","summary":"Get listing detail","description":"Get full details of a listing including specifications, seller info, and teaser research data.","tags":["Listings"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Listing detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"404":{"description":"Listing not found"}},"x-curl-example":"curl 'http://localhost:3000/api/agent/listings/mp-1'"}},"/api/agent/categories":{"get":{"operationId":"getCategories","summary":"List categories","description":"Get all product categories and subcategories.","tags":["Categories"],"responses":{"200":{"description":"Category list"}},"x-curl-example":"curl 'http://localhost:3000/api/agent/categories'"}},"/api/agent/cross-match/{id}":{"get":{"operationId":"getCrossMatch","summary":"Cross-match listing","description":"Find the same or similar product across auctions, marketplace, and external platforms. Great for price comparison.","tags":["Price Comparison"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cross-match results"},"404":{"description":"Listing not found"}},"x-curl-example":"curl 'http://localhost:3000/api/agent/cross-match/mp-1'"}},"/api/agent/research":{"post":{"operationId":"deepResearch","summary":"Deep research","description":"AI-powered deep research on a listing. Returns condition analysis, market pricing, parts breakdown, and profitability. Requires auth and costs credits.","tags":["Research"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["listingId"],"properties":{"listingId":{"type":"string"},"depth":{"type":"string","enum":["basic","full","premium"],"default":"basic","description":"basic=10cr, full=30cr, premium=50cr"}}}}}},"responses":{"200":{"description":"Research results"},"401":{"description":"Auth required"},"402":{"description":"Insufficient credits or rate limit"},"404":{"description":"Listing not found"}},"x-curl-example":"curl -X POST 'http://localhost:3000/api/agent/research' -H 'Authorization: Bearer erches_agent_demo_pro' -H 'Content-Type: application/json' -d '{\"listingId\":\"mp-1\",\"depth\":\"full\"}'"}},"/api/agent/bid":{"post":{"operationId":"placeBid","summary":"Place auction bid","description":"Place a bid on an auction listing. Requires Pro or Enterprise tier.","tags":["Auction"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["listingId","amount"],"properties":{"listingId":{"type":"string"},"amount":{"type":"number","description":"Bid amount in EUR"}}}}}},"responses":{"200":{"description":"Bid placed"},"400":{"description":"Bid too low or not an auction"},"401":{"description":"Auth required"},"403":{"description":"Pro tier required"}},"x-curl-example":"curl -X POST 'http://localhost:3000/api/agent/bid' -H 'Authorization: Bearer erches_agent_demo_pro' -H 'Content-Type: application/json' -d '{\"listingId\":\"es-1\",\"amount\":5000}'"}},"/api/agent/buy":{"post":{"operationId":"buyItem","summary":"Buy marketplace item","description":"Start a purchase. Returns a checkout token valid for 30 minutes. Confirm with /api/agent/checkout/confirm.","tags":["Purchase"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["listingId"],"properties":{"listingId":{"type":"string"},"delivery_method":{"type":"string","enum":["pickup","shipping"],"default":"shipping"}}}}}},"responses":{"200":{"description":"Checkout token with price breakdown"},"401":{"description":"Auth required"},"403":{"description":"Pro tier required"}},"x-curl-example":"curl -X POST 'http://localhost:3000/api/agent/buy' -H 'Authorization: Bearer erches_agent_demo_pro' -H 'Content-Type: application/json' -d '{\"listingId\":\"mp-1\"}'"}},"/api/agent/checkout/confirm":{"post":{"operationId":"confirmCheckout","summary":"Confirm purchase","description":"Confirm a purchase using the checkout token from /api/agent/buy.","tags":["Purchase"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["checkout_token"],"properties":{"checkout_token":{"type":"string"}}}}}},"responses":{"200":{"description":"Order confirmed"},"400":{"description":"Invalid or expired token"},"401":{"description":"Auth required"}}}},"/api/agent/listings/create":{"post":{"operationId":"createListing","summary":"Create a marketplace listing","description":"Create a new marketplace listing on behalf of a user. Requires Pro or Enterprise tier. Costs 5 credits per listing.","tags":["Listings"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","description","price","category"],"properties":{"title":{"type":"string","minLength":5,"description":"Listing title (min 5 chars)"},"description":{"type":"string","minLength":20,"description":"Listing description (min 20 chars)"},"price":{"type":"number","minimum":0.01,"description":"Price in EUR"},"category":{"type":"string","description":"Category name (e.g., \"Elektronica\", \"Voertuigen\")"},"condition":{"type":"string","enum":["nieuw","zo-goed-als-nieuw","goed","redelijk","voor-onderdelen"],"default":"goed"},"images":{"type":"array","items":{"type":"string"},"description":"Image URLs"},"delivery":{"type":"object","properties":{"pickup":{"type":"boolean","default":true},"shipping":{"type":"boolean","default":false}}}}}}}},"responses":{"200":{"description":"Listing created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"description":"Validation error"},"401":{"description":"Auth required"},"403":{"description":"Pro tier required"}},"x-curl-example":"curl -X POST 'http://localhost:3000/api/agent/listings/create' -H 'Authorization: Bearer erches_agent_demo_pro' -H 'Content-Type: application/json' -d '{\"title\":\"iPhone 15 Pro 256GB\",\"description\":\"Excellent condition iPhone 15 Pro with original box and accessories\",\"price\":899,\"category\":\"Elektronica\"}'"}},"/api/agent/batch-search":{"post":{"operationId":"batchSearch","summary":"Batch search multiple queries","description":"Search for up to 10 items at once. Returns results for each query.","tags":["Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["queries"],"properties":{"queries":{"type":"array","maxItems":10,"items":{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"category":{"type":"string"},"maxPrice":{"type":"number","description":"Maximum price in EUR"},"condition":{"type":"string","enum":["new","like_new","good","fair","for_parts"]}}}}}}}}},"responses":{"200":{"description":"Batch search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"400":{"description":"Invalid queries array"}},"x-curl-example":"curl -X POST 'http://localhost:3000/api/agent/batch-search' -H 'Content-Type: application/json' -d '{\"queries\":[{\"query\":\"iphone\"},{\"query\":\"samsung\"}]}'"}},"/api/agent/credits":{"get":{"operationId":"getCredits","summary":"Check credit balance","description":"Get current credit balance and tier info.","tags":["Account"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Credit info"},"401":{"description":"Auth required"}},"x-curl-example":"curl 'http://localhost:3000/api/agent/credits' -H 'Authorization: Bearer erches_agent_demo_pro'"}}}}