{"info":{"title":"Neeed Directory API","version":"1.0.0","description":"Read access to the live catalog: search and list products, list categories, fetch one listing. No key needed; requests are limited per IP.","contact":{"email":"support@neeed.directory"}},"servers":[{"url":"https://mcp-preview.neeed.directory/api/v1"}],"openapi":"3.1.2","components":{"schemas":{"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"slug":{"type":"string"},"name":{"type":"string"},"punchline":{"type":"string","description":"The one-line tagline"},"description":{"type":"string","description":"HTML, as the listing page renders it"},"url":{"type":"string","format":"uri","description":"The listing on Neeed Directory"},"website":{"type":"string","description":"The product's own site"},"logo":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"cover":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Category slug"},"labels":{"type":"array","items":{"type":"string"},"description":"Label slugs"},"tags":{"type":"array","items":{"type":"string"},"description":"Tag slugs"},"product_type":{"anyOf":[{"type":"string","enum":["software","digital_product"]},{"type":"null"}]},"pricing_model":{"anyOf":[{"type":"string","enum":["free","freemium","paid","open_source"]},{"type":"null"}]},"twitter":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"X handle, without the @"},"featured":{"type":"boolean"},"listed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}],"description":"When the listing went live"},"highlights":{"type":"array","items":{"type":"string"},"description":"Premium profile: what it does, one fact per line"},"ideal_for":{"type":"array","items":{"type":"string"},"description":"Premium profile: who it is for"},"faq":{"type":"array","items":{"$ref":"#/components/schemas/FaqItem"},"description":"Premium profile: questions answered from the product's site"},"promo":{"anyOf":[{"$ref":"#/components/schemas/Promo"},{"type":"null"}],"description":"The maker's promo code for visitors, or null"}},"required":["id","slug","name","punchline","description","url","website","logo","cover","category","labels","tags","product_type","pricing_model","twitter","featured","listed_at","highlights","ideal_for","faq","promo"],"additionalProperties":false},"FaqItem":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"],"additionalProperties":false},"Promo":{"type":"object","properties":{"code":{"type":"string"},"discount":{"type":"string","description":"The offer, in the maker's words: \"20% off\""},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Where to redeem it; null means the product's own site"},"expires_at":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}],"description":"Last valid day, yyyy-mm-dd; null means open-ended"}},"required":["code","discount","url","expires_at"],"additionalProperties":false},"Category":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"noun":{"type":"string","description":"What the directory calls its listings, e.g. \"AI agents\""},"url":{"type":"string","format":"uri"},"count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Live listings in the category"}},"required":["slug","name","noun","url","count"],"additionalProperties":false}}},"paths":{"/search":{"get":{"operationId":"searchProducts","summary":"Search or list products","description":"Live listings, newest first. Narrow them with a full-text query and by category, label or tag; every filter is optional.","tags":["Products"],"parameters":[{"in":"query","name":"q","schema":{"description":"Full-text query over name, tagline and description","type":"string","minLength":2,"maxLength":100},"allowEmptyValue":true,"allowReserved":true},{"in":"query","name":"category","schema":{"description":"Category slug","type":"string"},"allowEmptyValue":true,"allowReserved":true},{"in":"query","name":"label","schema":{"description":"Label slug","type":"string"},"allowEmptyValue":true,"allowReserved":true},{"in":"query","name":"tag","schema":{"description":"Tag slug","type":"string"},"allowEmptyValue":true,"allowReserved":true},{"in":"query","name":"page","schema":{"default":1,"description":"Page number","type":"integer","minimum":1,"maximum":500},"allowEmptyValue":true,"allowReserved":true},{"in":"query","name":"limit","schema":{"default":20,"description":"Products per page","type":"integer","minimum":1,"maximum":50},"allowEmptyValue":true,"allowReserved":true}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"total":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Matches across every page"},"page":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["products","total","page","limit"],"additionalProperties":false}}}},"400":{"description":"Invalid input, with the rejected parameters under data.issues","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"description":"The validation issues, on a 400"}},"required":["code","message"]}}}},"429":{"description":"Too many requests. Please slow down and try again shortly.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"description":"The validation issues, on a 400"}},"required":["code","message"]}}}}}}},"/categories":{"get":{"operationId":"listCategories","summary":"List categories","description":"Every category with the number of live listings it holds, by name.","tags":["Categories"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}},"required":["categories"],"additionalProperties":false}}}},"429":{"description":"Too many requests. Please slow down and try again shortly.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"description":"The validation issues, on a 400"}},"required":["code","message"]}}}}}}},"/products/{slug}":{"get":{"operationId":"getProduct","summary":"Get a product","description":"One live listing by slug. A listing that is not live is a 404.","tags":["Products"],"parameters":[{"in":"path","required":true,"name":"slug","schema":{"type":"string","minLength":1,"maxLength":200,"description":"The slug in the listing's URL"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"Invalid input, with the rejected parameters under data.issues","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"description":"The validation issues, on a 400"}},"required":["code","message"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"description":"The validation issues, on a 400"}},"required":["code","message"]}}}},"429":{"description":"Too many requests. Please slow down and try again shortly.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"data":{"description":"The validation issues, on a 400"}},"required":["code","message"]}}}}}}}}}