{"openapi":"3.1.0","info":{"title":"NeedAnAI Agent API","version":"1.0.0","description":"Read the NeedAnAI catalogue of 15,000+ AI tools. Anonymous reads are free (fair-use limits); watches, submissions and exports need a free API key. The same capabilities are available over MCP at https://mcp.needanai.com/mcp.","contact":{"url":"https://needanai.com/developers"},"x-mcp-server":"https://mcp.needanai.com/mcp"},"servers":[{"url":"https://api.needanai.com"}],"tags":[{"name":"catalogue","description":"Public, anonymous reads"},{"name":"keyed","description":"Requires Authorization: Bearer nai_…"}],"paths":{"/v1/tools":{"get":{"operationId":"search_tools","summary":"Search tools","description":"Search the NeedAnAI catalogue of 15,000+ AI tools by free text, pricing model, category or task. Returns ranked hits with pricing, status, freshness (when the site was last confirmed alive) and canonical URLs, plus facet counts and a separate, labelled sponsored block. Use list_taxonomy for valid category and task slugs.","tags":["catalogue"],"parameters":[{"name":"query","in":"query","required":false,"schema":{"description":"Free text, e.g. \"video editing\" or a tool name. Empty lists the catalogue.","type":"string","maxLength":200},"description":"Free text, e.g. \"video editing\" or a tool name. Empty lists the catalogue."},{"name":"pricing","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated list"},"description":"Restrict to these pricing models."},{"name":"category","in":"query","required":false,"schema":{"description":"Category slug from list_taxonomy.","type":"string","maxLength":120},"description":"Category slug from list_taxonomy."},{"name":"task","in":"query","required":false,"schema":{"description":"Task slug from list_taxonomy.","type":"string","maxLength":120},"description":"Task slug from list_taxonomy."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["relevance","recent"]}},{"name":"page","in":"query","required":false,"schema":{"description":"1-based page number.","type":"integer","minimum":1,"maximum":400},"description":"1-based page number."},{"name":"perPage","in":"query","required":false,"schema":{"description":"Results per page, max 25.","type":"integer","minimum":1,"maximum":25},"description":"Results per page, max 25."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"hits":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"pricingType":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"tasks":{"type":"array","items":{"type":"string"}},"url":{"type":"string"},"websiteUrl":{"type":["string","null"]},"siteStatus":{"type":"string"},"freshness":{"type":"object","properties":{"label":{"type":"string","enum":["fresh","aging","stale","unknown"],"description":"fresh ≤30 days, aging ≤90 days, stale beyond, unknown when never checked"},"basis":{"type":"string","enum":["verified","checked","none"]},"at":{"type":["string","null"]},"ageDays":{"type":["number","null"]}},"required":["label","basis","at","ageDays"],"additionalProperties":{}}},"required":["slug","name","summary","pricingType","categories","tasks","url","websiteUrl","siteStatus","freshness"],"additionalProperties":{}}},"total":{"type":"number"},"page":{"type":"number"},"pages":{"type":"number"},"perPage":{"type":"number"},"facets":{"type":"object","properties":{"pricing":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"categories":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"tasks":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}}},"required":["pricing","categories","tasks"],"additionalProperties":{}},"sponsored":{"type":"object","properties":{"disclosure":{"type":"string","description":"Always present. Sponsored items are never mixed into ranked results."},"items":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"pricingType":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"tasks":{"type":"array","items":{"type":"string"}},"url":{"type":"string"},"websiteUrl":{"type":["string","null"]},"siteStatus":{"type":"string"},"freshness":{"type":"object","properties":{"label":{"type":"string","enum":["fresh","aging","stale","unknown"],"description":"fresh ≤30 days, aging ≤90 days, stale beyond, unknown when never checked"},"basis":{"type":"string","enum":["verified","checked","none"]},"at":{"type":["string","null"]},"ageDays":{"type":["number","null"]}},"required":["label","basis","at","ageDays"],"additionalProperties":{}}},"required":["slug","name","summary","pricingType","categories","tasks","url","websiteUrl","siteStatus","freshness"],"additionalProperties":{}}}},"required":["disclosure","items"],"additionalProperties":{}}},"required":["query","hits","total","page","pages","perPage","facets","sponsored"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"x-mcp-tool":"search_tools","x-read-only":true}},"/v1/tools/{slug}":{"get":{"operationId":"get_tool","summary":"Get a tool","description":"Full profile of one tool by slug: description, pricing model and details (with when pricing was last checked), pricing history, pros, cons, FAQs, categories, tasks, media, site status, freshness and up to five alternatives. Ends with a provenance line.","tags":["catalogue"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,190}$","description":"Tool slug as it appears in https://needanai.com/tool/<slug>"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"description":{"type":"string"},"websiteUrl":{"type":["string","null"]},"pricing":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"details":{"type":"string"},"checkedAt":{"type":["string","null"]}},"required":["type","label","details","checkedAt"],"additionalProperties":{}},"pricingHistory":{"type":"array","items":{"type":"object","properties":{"capturedAt":{"type":"string"},"type":{"type":"string"},"details":{"type":"string"}},"required":["capturedAt","type","details"],"additionalProperties":{}}},"pros":{"type":"array","items":{"type":"string"}},"cons":{"type":"array","items":{"type":"string"}},"faqs":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"],"additionalProperties":{}}},"categories":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string"}},"required":["name","slug","url"],"additionalProperties":{}}},"tasks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string"}},"required":["name","slug","url"],"additionalProperties":{}}},"tags":{"type":"array","items":{"type":"string"}},"jobs":{"type":"array","items":{"type":"string"}},"media":{"type":"object","properties":{"logoUrl":{"type":["string","null"]},"screenshotUrl":{"type":["string","null"]}},"required":["logoUrl","screenshotUrl"],"additionalProperties":{}},"flags":{"type":"object","properties":{"trending":{"type":"boolean"},"verified":{"type":"boolean"}},"required":["trending","verified"],"additionalProperties":{}},"launchDate":{"type":["string","null"]},"siteStatus":{"type":"string"},"freshness":{"type":"object","properties":{"label":{"type":"string","enum":["fresh","aging","stale","unknown"],"description":"fresh ≤30 days, aging ≤90 days, stale beyond, unknown when never checked"},"basis":{"type":"string","enum":["verified","checked","none"]},"at":{"type":["string","null"]},"ageDays":{"type":["number","null"]}},"required":["label","basis","at","ageDays"],"additionalProperties":{}},"source":{"type":"object","properties":{"url":{"type":"string"},"checkedAt":{"type":["string","null"]},"verifiedAt":{"type":["string","null"]},"publishedAt":{"type":["string","null"]}},"required":["url","checkedAt","verifiedAt","publishedAt"],"additionalProperties":{}},"alternatives":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"pricingType":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"tasks":{"type":"array","items":{"type":"string"}},"url":{"type":"string"},"websiteUrl":{"type":["string","null"]},"siteStatus":{"type":"string"},"freshness":{"type":"object","properties":{"label":{"type":"string","enum":["fresh","aging","stale","unknown"],"description":"fresh ≤30 days, aging ≤90 days, stale beyond, unknown when never checked"},"basis":{"type":"string","enum":["verified","checked","none"]},"at":{"type":["string","null"]},"ageDays":{"type":["number","null"]}},"required":["label","basis","at","ageDays"],"additionalProperties":{}}},"required":["slug","name","summary","pricingType","categories","tasks","url","websiteUrl","siteStatus","freshness"],"additionalProperties":{}}}},"required":["slug","name","summary","description","websiteUrl","pricing","pros","cons","faqs","categories","tasks","tags","jobs","media","flags","launchDate","siteStatus","freshness","source","alternatives"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"x-mcp-tool":"get_tool","x-read-only":true}},"/v1/tools/{slug}/alternatives":{"get":{"operationId":"find_alternatives","summary":"Alternatives to a tool","description":"Alternatives to a tool, ranked by freshness, profile completeness, curation and how many other tools list them as an alternative. Each entry carries a rationale. Optionally restrict to the same pricing model.","tags":["catalogue"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,190}$","description":"Tool slug as it appears in https://needanai.com/tool/<slug>"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25}},{"name":"samePricing","in":"query","required":false,"schema":{"description":"Only alternatives with the same pricing model.","type":"boolean"},"description":"Only alternatives with the same pricing model."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tool":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"pricingType":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"tasks":{"type":"array","items":{"type":"string"}},"url":{"type":"string"},"websiteUrl":{"type":["string","null"]},"siteStatus":{"type":"string"},"freshness":{"type":"object","properties":{"label":{"type":"string","enum":["fresh","aging","stale","unknown"],"description":"fresh ≤30 days, aging ≤90 days, stale beyond, unknown when never checked"},"basis":{"type":"string","enum":["verified","checked","none"]},"at":{"type":["string","null"]},"ageDays":{"type":["number","null"]}},"required":["label","basis","at","ageDays"],"additionalProperties":{}}},"required":["slug","name","summary","pricingType","categories","tasks","url","websiteUrl","siteStatus","freshness"],"additionalProperties":{}},"alternatives":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"pricingType":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"tasks":{"type":"array","items":{"type":"string"}},"url":{"type":"string"},"websiteUrl":{"type":["string","null"]},"siteStatus":{"type":"string"},"freshness":{"type":"object","properties":{"label":{"type":"string","enum":["fresh","aging","stale","unknown"],"description":"fresh ≤30 days, aging ≤90 days, stale beyond, unknown when never checked"},"basis":{"type":"string","enum":["verified","checked","none"]},"at":{"type":["string","null"]},"ageDays":{"type":["number","null"]}},"required":["label","basis","at","ageDays"],"additionalProperties":{}},"score":{"type":"number"},"rationale":{"type":"array","items":{"type":"string"}}},"required":["slug","name","summary","pricingType","categories","tasks","url","websiteUrl","siteStatus","freshness","score","rationale"],"additionalProperties":{}}}},"required":["tool","alternatives"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"x-mcp-tool":"find_alternatives","x-read-only":true}},"/v1/compare":{"get":{"operationId":"compare_tools","summary":"Compare tools (slugs=a,b,c)","description":"Side-by-side comparison of 2–5 tools: pricing, summary, categories, tasks, pros, cons, site status, freshness, flags and launch date.","tags":["catalogue"],"parameters":[{"name":"slugs","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated list"},"description":"2 to 5 tool slugs."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"websiteUrl":{"type":["string","null"]}},"required":["slug","name","url","websiteUrl"],"additionalProperties":{}}},"rows":{"type":"array","items":{"type":"object","properties":{"attribute":{"type":"string"},"values":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["attribute","values"],"additionalProperties":{}}},"missing":{"type":"array","items":{"type":"string"}}},"required":["tools","rows","missing"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"x-mcp-tool":"compare_tools","x-read-only":true}},"/v1/recommendations":{"get":{"operationId":"recommend_for_task","summary":"Recommend tools for a task","description":"Given a job to be done (\"create a logo\", \"transcribe meetings\") and an optional budget, returns the best-fitting tools with an explicit rationale per recommendation. Resolves known task slugs first, then falls back to free-text search.","tags":["catalogue"],"parameters":[{"name":"task","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":200,"description":"What the user wants to do, e.g. \"create a logo\", or a task slug."},"description":"What the user wants to do, e.g. \"create a logo\", or a task slug."},{"name":"budget","in":"query","required":false,"schema":{"type":"string","enum":["free","freemium","paid","any"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"string"},"matchedTask":{"anyOf":[{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}},"required":["slug","name"],"additionalProperties":{}},{"type":"null"}]},"budget":{"type":"string"},"recommendations":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"pricingType":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"tasks":{"type":"array","items":{"type":"string"}},"url":{"type":"string"},"websiteUrl":{"type":["string","null"]},"siteStatus":{"type":"string"},"freshness":{"type":"object","properties":{"label":{"type":"string","enum":["fresh","aging","stale","unknown"],"description":"fresh ≤30 days, aging ≤90 days, stale beyond, unknown when never checked"},"basis":{"type":"string","enum":["verified","checked","none"]},"at":{"type":["string","null"]},"ageDays":{"type":["number","null"]}},"required":["label","basis","at","ageDays"],"additionalProperties":{}},"score":{"type":"number"},"rationale":{"type":"array","items":{"type":"string"}}},"required":["slug","name","summary","pricingType","categories","tasks","url","websiteUrl","siteStatus","freshness","score","rationale"],"additionalProperties":{}}},"considered":{"type":"number"}},"required":["task","matchedTask","budget","recommendations","considered"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"x-mcp-tool":"recommend_for_task","x-read-only":true}},"/v1/categories":{"get":{"operationId":"list_taxonomy_categories","summary":"List categories","description":"All category or task slugs with names and live tool counts. Use the slugs as filters for search_tools and recommend_for_task.","tags":["catalogue"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"count":{"type":"number"},"url":{"type":"string"}},"required":["slug","name","description","count","url"],"additionalProperties":{}}}},"required":["kind","items"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"x-mcp-tool":"list_taxonomy","x-read-only":true}},"/v1/tasks":{"get":{"operationId":"list_taxonomy_tasks","summary":"List tasks","description":"All category or task slugs with names and live tool counts. Use the slugs as filters for search_tools and recommend_for_task.","tags":["catalogue"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"count":{"type":"number"},"url":{"type":"string"}},"required":["slug","name","description","count","url"],"additionalProperties":{}}}},"required":["kind","items"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"x-mcp-tool":"list_taxonomy","x-read-only":true}},"/v1/articles":{"get":{"operationId":"search_articles","summary":"Search articles","description":"Search 660+ editorial articles (reviews, comparisons, alternatives round-ups, guides) by keywords and optional category.","tags":["catalogue"],"parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"category","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"total":{"type":"number"},"articles":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"readingMinutes":{"type":"number"},"url":{"type":"string"}},"required":["slug","title","description","category","readingMinutes","url"],"additionalProperties":{}}}},"required":["query","total","articles"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"x-mcp-tool":"search_articles","x-read-only":true}},"/v1/articles/{slug}":{"get":{"operationId":"get_article","summary":"Get an article","description":"The full markdown body of one article by slug.","tags":["catalogue"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,190}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"readingMinutes":{"type":"number"},"url":{"type":"string"},"markdown":{"type":"string"}},"required":["slug","title","description","category","readingMinutes","url","markdown"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"x-mcp-tool":"get_article","x-read-only":true}},"/v1/tools/{slug}/status":{"get":{"operationId":"check_status","summary":"Check a tool’s status","description":"Is the tool’s site alive? Returns the scanner verdict, when it was last checked and verified, when pricing was last checked, and a freshness label.","tags":["catalogue"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,190}$","description":"Tool slug as it appears in https://needanai.com/tool/<slug>"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"websiteUrl":{"type":["string","null"]},"siteStatus":{"type":"string"},"freshness":{"type":"object","properties":{"label":{"type":"string","enum":["fresh","aging","stale","unknown"],"description":"fresh ≤30 days, aging ≤90 days, stale beyond, unknown when never checked"},"basis":{"type":"string","enum":["verified","checked","none"]},"at":{"type":["string","null"]},"ageDays":{"type":["number","null"]}},"required":["label","basis","at","ageDays"],"additionalProperties":{}},"checkedAt":{"type":["string","null"]},"verifiedAt":{"type":["string","null"]},"pricingCheckedAt":{"type":["string","null"]},"note":{"type":"string"}},"required":["slug","name","url","websiteUrl","siteStatus","freshness","checkedAt","verifiedAt","pricingCheckedAt","note"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"x-mcp-tool":"check_status","x-read-only":true}},"/v1/watches":{"post":{"operationId":"watch_tool","summary":"Create a watch","description":"Subscribe to status and pricing changes for a tool (checked every 30 minutes). Delivered to an https webhook or email. Requires an API key (free, from https://needanai.com/profile?tab=api-keys).","tags":["keyed"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,190}$","description":"Tool slug as it appears in https://needanai.com/tool/<slug>"},"channel":{"type":"string","enum":["webhook","email"]},"target":{"type":"string","minLength":3,"maxLength":2048,"description":"https webhook URL or email address"}},"required":["slug","channel","target"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"toolSlug":{"type":"string"},"channel":{"type":"string"},"target":{"type":"string"},"lastNotifiedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","toolSlug","channel","target","lastNotifiedAt","createdAt"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}],"x-mcp-tool":"watch_tool","x-read-only":false},"get":{"operationId":"list_watches","summary":"List watches","description":"Active watches on this API key.","tags":["keyed"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"watches":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"toolSlug":{"type":"string"},"channel":{"type":"string"},"target":{"type":"string"},"lastNotifiedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","toolSlug","channel","target","lastNotifiedAt","createdAt"],"additionalProperties":{}}}},"required":["watches"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}],"x-mcp-tool":"list_watches","x-read-only":true}},"/v1/watches/{id}":{"delete":{"operationId":"unwatch_tool","summary":"Delete a watch","description":"Stop a watch by id.","tags":["keyed"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"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)$"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"revoked":{"type":"boolean","const":true}},"required":["id","revoked"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}],"x-mcp-tool":"unwatch_tool","x-read-only":false}},"/v1/submissions":{"post":{"operationId":"submit_tool","summary":"Submit a tool","description":"Suggest a tool for the catalogue. If its website is already listed the existing listing is returned instead. Requires an API key.","tags":["keyed"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80},"url":{"type":"string","maxLength":2048,"format":"uri"},"description":{"type":"string","minLength":20,"maxLength":2000},"pricingType":{"type":"string","enum":["free","freemium","paid","subscription","free-trial","contact"]}},"required":["name","url","description"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["submitted","already_listed"]},"submissionId":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"tool":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"pricingType":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"tasks":{"type":"array","items":{"type":"string"}},"url":{"type":"string"},"websiteUrl":{"type":["string","null"]},"siteStatus":{"type":"string"},"freshness":{"type":"object","properties":{"label":{"type":"string","enum":["fresh","aging","stale","unknown"],"description":"fresh ≤30 days, aging ≤90 days, stale beyond, unknown when never checked"},"basis":{"type":"string","enum":["verified","checked","none"]},"at":{"type":["string","null"]},"ageDays":{"type":["number","null"]}},"required":["label","basis","at","ageDays"],"additionalProperties":{}}},"required":["slug","name","summary","pricingType","categories","tasks","url","websiteUrl","siteStatus","freshness"],"additionalProperties":{}}},"required":["status"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}],"x-mcp-tool":"submit_tool","x-read-only":false}},"/v1/exports":{"post":{"operationId":"export_tools","summary":"Create an export","description":"Bulk export of a filtered slice of the catalogue (up to 2,000 rows) as JSON or CSV. Returns a signed download URL valid for 24 hours. Requires an API key.","tags":["keyed"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":200},"pricing":{"type":"array","items":{"type":"string","enum":["free","freemium","paid","subscription","free-trial","contact"]}},"category":{"type":"string","maxLength":120},"task":{"type":"string","maxLength":120},"format":{"type":"string","enum":["json","csv"]},"maxRows":{"type":"integer","minimum":1,"maximum":2000}},"additionalProperties":false,"required":[]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"format":{"type":"string"},"rows":{"type":"number"},"createdAt":{"type":"string"},"expiresAt":{"type":"string"},"url":{"type":"string","description":"Signed download URL, valid until expiresAt."},"truncated":{"type":"boolean"}},"required":["id","format","rows","createdAt","expiresAt","url","truncated"],"additionalProperties":{}}}}},"400":{"$ref":"#/components/responses/Problem"},"401":{"$ref":"#/components/responses/Problem"},"404":{"$ref":"#/components/responses/Problem"},"429":{"$ref":"#/components/responses/Problem"},"503":{"$ref":"#/components/responses/Problem"}},"security":[{"apiKey":[]}],"x-mcp-tool":"export_tools","x-read-only":false}},"/v1/exports/{id}":{"get":{"operationId":"download_export","summary":"Download an export","description":"Signed URL returned by export_tools. Query: exp (epoch seconds), sig (HMAC).","tags":["keyed"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"exp","in":"query","required":true,"schema":{"type":"integer"}},{"name":"sig","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The export body (JSON or CSV)"},"404":{"$ref":"#/components/responses/Problem"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"nai_<key>"}},"responses":{"Problem":{"description":"RFC 9457 problem document","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"number"},"detail":{"type":"string"},"kind":{"type":"string"}},"required":["type","title","status","detail","kind"],"additionalProperties":{}}}}}}}}