{"openapi":"3.0.3","info":{"title":"Agentic.ai Directory API","version":"1.3.0","description":"Public read-only API for the Agentic.ai directory of agentic AI tools.\n\n- Agent manifest: https://agentic.ai/.well-known/agent.json\n- LLM guidance: https://agentic.ai/llms.txt\n- Rate limit: 100 requests/hour (unauthenticated)","contact":{"name":"Agentic.ai","url":"https://agentic.ai","email":"hello@agentic.ai"},"license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://agentic.ai/api/v1","description":"Production"}],"paths":{"/categories":{"get":{"operationId":"listCategories","summary":"List all categories","description":"Returns all categories with listing counts, ordered by cohort and display order.","responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoriesResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/categories/{slug}":{"get":{"operationId":"getCategory","summary":"Get category with listings","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"ai-coding-assistants"}],"responses":{"200":{"description":"Category with listings"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/listings":{"get":{"operationId":"listListings","summary":"List and filter listings","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Items per page"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category slug","example":"ai-coding-assistants"},{"name":"tag","in":"query","schema":{"type":"string"},"description":"Filter by tag slug"},{"name":"cohort","in":"query","schema":{"type":"string","enum":["PEOPLE","TEAMS"]},"description":"Filter by cohort"},{"name":"minScore","in":"query","schema":{"type":"integer","minimum":0,"maximum":36},"description":"Minimum agenticness score (rubric v3.1 is scored out of 36)"},{"name":"sort","in":"query","schema":{"type":"string","enum":["score","newest","name"],"default":"score"},"description":"Sort order"},{"name":"deployment","in":"query","schema":{"type":"string","enum":["CLOUD","SELF_HOSTED","HYBRID","ON_DEVICE"]},"description":"Filter by deployment model"},{"name":"autonomy","in":"query","schema":{"type":"string","enum":["COPILOT","SEMI_AUTONOMOUS","FULLY_AUTONOMOUS"]},"description":"Filter by autonomy level"},{"name":"openSource","in":"query","schema":{"type":"boolean"},"description":"Filter by open-source status"},{"name":"mcpSupport","in":"query","schema":{"type":"boolean"},"description":"Filter by MCP support"}],"responses":{"200":{"description":"Paginated list of listings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingsResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/listings/{slug}":{"get":{"operationId":"getListing","summary":"Get listing detail","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"cursor"}],"responses":{"200":{"description":"Full listing detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingDetailResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/tags":{"get":{"operationId":"listTags","summary":"List all tags","description":"Returns all active tags grouped by type.","responses":{"200":{"description":"List of tags","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagsResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/search":{"get":{"operationId":"searchListings","summary":"Search listings","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query","example":"code review"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Limit to category slug"},{"name":"cohort","in":"query","schema":{"type":"string","enum":["PEOPLE","TEAMS"]},"description":"Limit to cohort"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingsResponse"}}}},"400":{"description":"Missing required parameter 'q'"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/recommend":{"post":{"operationId":"recommendTools","summary":"AI-powered tool recommendations","description":"Natural-language recommendations with ranked reasoning. HTTP mirror of the MCP `recommend_tools` tool — runs hybrid search + structured filters in one call and returns a ranked list with `whyRecommended` per tool. Use this instead of chaining /search + /listings/{slug}.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendRequest"},"example":{"question":"self-hosted coding agent with MCP support","constraints":{"selfHosted":true,"mcpSupport":true,"maxResults":5}}}}},"responses":{"200":{"description":"Ranked recommendations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendResponse"}}}},"400":{"description":"Invalid request body"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/compare":{"get":{"operationId":"compareListings","summary":"Compare two tools side-by-side","description":"Returns a structured comparison of two tools including full details and an AI-generated verdict.","parameters":[{"name":"tools","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated slugs of two tools to compare","example":"cursor,github-copilot"}],"responses":{"200":{"description":"Tool comparison","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareResponse"}}}},"400":{"description":"Invalid or missing tools parameter (exactly 2 slugs required)"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"schemas":{"ApiMeta":{"type":"object","properties":{"api_version":{"type":"string","example":"v1"},"cached":{"type":"boolean"},"generated_at":{"type":"string","format":"date-time"}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"},"totalPages":{"type":"integer"}}},"Category":{"type":"object","properties":{"slug":{"type":"string","example":"ai-coding-assistants"},"name":{"type":"string","example":"AI Coding Assistants"},"description":{"type":"string","nullable":true},"cohort":{"type":"string","enum":["PEOPLE","TEAMS"]},"listingCount":{"type":"integer","example":12}}},"ListingSummary":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string","nullable":true},"shortDescription":{"type":"string"},"vendorUrl":{"type":"string","format":"uri"},"agenticScore":{"type":"integer","nullable":true,"minimum":0,"maximum":36,"description":"Raw agenticness rubric total, 0-36 across 9 dimensions (rubric v3.1). NOTE: for a small number of listings the website displays an evidence-adjusted figure that can differ from this value; this field is the rubric total and is always consistent with agenticnessDimensions."},"agenticnessLabel":{"type":"string","nullable":true,"description":"Named level: Reactive Tool, Guided Assistant, Adaptive Collaborator, Domain Specialist, Autonomous Operator, or Strategic Agent"},"categories":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"deploymentModel":{"type":"string","nullable":true,"enum":["CLOUD","SELF_HOSTED","HYBRID","ON_DEVICE"],"description":"How the tool is deployed"},"autonomyLevel":{"type":"string","nullable":true,"enum":["COPILOT","SEMI_AUTONOMOUS","FULLY_AUTONOMOUS"],"description":"Level of autonomous operation"},"openSource":{"type":"boolean","nullable":true,"description":"Whether the tool is open source"},"mcpSupport":{"type":"boolean","nullable":true,"description":"Whether the tool supports Model Context Protocol"}}},"ListingDetail":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string","nullable":true},"shortDescription":{"type":"string"},"longDescription":{"type":"string","nullable":true},"vendorUrl":{"type":"string","format":"uri"},"agenticScore":{"type":"integer","nullable":true,"minimum":0,"maximum":36,"description":"Raw agenticness rubric total, 0-36 across 9 dimensions (rubric v3.1). NOTE: for a small number of listings the website displays an evidence-adjusted figure that can differ from this value; this field is the rubric total and is always consistent with agenticnessDimensions."},"agenticLevel":{"type":"integer","nullable":true,"minimum":0,"maximum":5},"agenticnessLabel":{"type":"string","nullable":true},"agenticSummary":{"type":"string","nullable":true},"categories":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"deploymentModel":{"type":"string","nullable":true,"enum":["CLOUD","SELF_HOSTED","HYBRID","ON_DEVICE"],"description":"How the tool is deployed"},"modelAgnosticism":{"type":"string","nullable":true,"enum":["SINGLE_MODEL","MULTI_MODEL","SUPPORTS_LOCAL"],"description":"Model flexibility"},"autonomyLevel":{"type":"string","nullable":true,"enum":["COPILOT","SEMI_AUTONOMOUS","FULLY_AUTONOMOUS"],"description":"Level of autonomous operation"},"teamSupport":{"type":"string","nullable":true,"enum":["INDIVIDUAL_ONLY","SMALL_TEAM","ENTERPRISE"],"description":"Team size support"},"pricingModel":{"type":"string","nullable":true,"enum":["FREE_OSS","FREEMIUM","SUBSCRIPTION","PER_SEAT","USAGE_BASED","HYBRID"],"description":"Pricing structure"},"mcpSupport":{"type":"boolean","nullable":true,"description":"Whether the tool supports Model Context Protocol"},"openSource":{"type":"boolean","nullable":true,"description":"Whether the tool is open source"},"primaryInterface":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Primary user interfaces (e.g. CLI, Web, IDE, API)"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Tag":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"group":{"type":"string","nullable":true}}},"CategoriesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"_meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ListingsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ListingSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"_meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ListingDetailResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ListingDetail"},"_meta":{"$ref":"#/components/schemas/ApiMeta"}}},"TagsResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"_meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ApiComparison":{"type":"object","properties":{"tool1":{"$ref":"#/components/schemas/ListingDetail"},"tool2":{"$ref":"#/components/schemas/ListingDetail"},"verdict":{"type":"object","properties":{"chooseTool1If":{"type":"array","items":{"type":"string"},"description":"Reasons to choose tool 1"},"chooseTool2If":{"type":"array","items":{"type":"string"},"description":"Reasons to choose tool 2"}}},"comparisonUrl":{"type":"string","format":"uri","description":"URL to the comparison page on agentic.ai"}}},"CompareResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiComparison"},"_meta":{"$ref":"#/components/schemas/ApiMeta"}}},"RecommendRequest":{"type":"object","required":["question"],"properties":{"question":{"type":"string","description":"Natural-language description of the task or need","example":"open source alternative to Cursor for VS Code"},"constraints":{"type":"object","properties":{"category":{"type":"string","description":"Category slug filter"},"cohort":{"type":"string","enum":["PEOPLE","TEAMS"]},"openSource":{"type":"boolean","description":"Require open source"},"selfHosted":{"type":"boolean","description":"Require self-hosted (SELF_HOSTED, HYBRID, or ON_DEVICE)"},"mcpSupport":{"type":"boolean","description":"Require MCP support"},"maxResults":{"type":"integer","minimum":1,"maximum":10,"default":5},"minRelevanceScore":{"type":"integer","minimum":0,"maximum":100,"description":"Drop recommendations whose relevanceScore is below this floor (0-100). Filtered hits are not counted in totalAfterFilters. Defaults to 0 (no floor)."}}}}},"StructuredPricing":{"type":"object","description":"Structured pricing summary derived from pricingModel + the free-form pricing string. The legacy pricing/pricingModel fields are still emitted alongside this object for backwards compatibility.","properties":{"model":{"type":"string","enum":["free","freemium","paid","open_source","usage_based","unknown"],"description":"Coarse pricing bucket suitable for a single chip in UI"},"freeTierAvailable":{"type":"boolean"},"startingPriceUsd":{"type":"integer","minimum":1,"description":"Best-effort starting price extracted from the free-form pricing string (e.g. 'From $60/mo' → 60). Omitted when no number can be confidently parsed."}},"required":["model","freeTierAvailable"]},"Recommendation":{"type":"object","properties":{"rank":{"type":"integer","minimum":1},"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"logoUrl":{"type":"string","format":"uri","nullable":true,"description":"Absolute URL to the listing logo (PNG/JPG/WebP). Null when no logo has been uploaded."},"tagline":{"type":"string","nullable":true},"description":{"type":"string"},"relevanceScore":{"type":"integer","minimum":0,"maximum":100,"description":"Search-pipeline relevance score (0-100). Present on every recommendation including rank #1. Use this for UX chips and as the threshold for minRelevanceScore."},"whyRecommended":{"type":"string","description":"Human-readable reason this tool fits the query — covers tagline, primary category fit, and any explicit constraints satisfied. Does NOT include the relevance score (use the relevanceScore field for that)."},"agenticScore":{"type":"integer","nullable":true,"minimum":0,"maximum":36,"description":"Raw agenticness rubric total, 0-36 across 9 dimensions (rubric v3.1). NOTE: for a small number of listings the website displays an evidence-adjusted figure that can differ from this value; this field is the rubric total and is always consistent with agenticnessDimensions."},"agenticLevel":{"type":"integer","nullable":true,"minimum":0,"maximum":5},"agenticnessLabel":{"type":"string","nullable":true},"deploymentModel":{"type":"string","nullable":true},"modelAgnosticism":{"type":"string","nullable":true},"autonomyLevel":{"type":"string","nullable":true},"teamSupport":{"type":"string","nullable":true},"pricingModel":{"type":"string","nullable":true,"description":"Legacy pricing-model label (e.g. 'Freemium'). Kept for Phase 1 clients. Prefer pricingDetails."},"pricingDetails":{"$ref":"#/components/schemas/StructuredPricing"},"mcpSupport":{"type":"boolean","nullable":true},"openSource":{"type":"boolean","nullable":true},"primaryInterface":{"type":"array","items":{"type":"string"}},"features":{"type":"array","items":{"type":"string"}},"useCases":{"type":"array","items":{"type":"string"}},"pricing":{"type":"string","nullable":true,"description":"Free-form pricing description from the listing (e.g. 'From $60/mo'). Kept for Phase 1 clients. Prefer pricingDetails for structured access."},"categories":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"dataCompleteness":{"type":"number","minimum":0,"maximum":1}}},"RecommendResponse":{"type":"object","properties":{"question":{"type":"string"},"constraintsApplied":{"type":"object"},"totalFound":{"type":"integer","description":"Hits returned by the search pipeline before structured filters"},"totalAfterFilters":{"type":"integer","description":"Hits after openSource/selfHosted/mcpSupport filtering"},"noMatches":{"type":"boolean","description":"True when recommendations is empty — lets clients show a graceful empty state without checking array length"},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/Recommendation"}},"directoryUrl":{"type":"string","format":"uri","description":"Link to the /ask page pre-seeded with the question"},"note":{"type":"string"},"_meta":{"$ref":"#/components/schemas/ApiMeta"}}},"ApiError":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"RateLimited":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until rate limit resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}