Use this endpoint when an agent needs ranked directory candidates instead of a raw catalog page.
When agents should use it
Use GET /api/v1/recommend for task-shaped questions where a user expects a short list of reviewed products, not every catalog match. Typical queries include:
- best agent-native support tools
- products built with Claude and Supabase
- agentic workflow tools for operations
- browser automation agents for founders
Input model
Provide at least one of:
taskstack
You can also set limit to constrain the number of returned recommendations.
Output model
The response includes normalized query data, resolved tool matches, and ranked recommendations with machine-readable reasoning fields so downstream agents can explain why a product was suggested.
Each recommendation includes the approved product record plus a match object. Use match.reasons, matched_tool_slugs, and task_match when explaining why a product was returned.
Creator visibility implications
App creators improve their chance of being returned by this endpoint when the listing has:
- clear
tool_slugsorcustom_tools - an accurate
agent_use_case - a reviewable
qualification_type - a plain
workflow_summary - public
supporting_links
Do not submit unsupported Agent Directory claims just to influence recommendations. Manual review can move weak claims out of Agent Directory eligibility.
/api/v1/recommendUse this endpoint when an agent needs shortlist-style recommendations instead of a generic catalog page.
Auth
No API keys. No account auth. Public JSON endpoints only.
Review model
Read-only endpoint over approved catalog and trust metadata.
Cache
Dynamic server response.
Example request
curl "https://www.madewithstack.com/api/v1/recommend?task=support&stack=claude,supabase&limit=3"
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
task | free-text task or canonical use case such as "support", "research", or "customer-support" | No | Task intent to match against agent use case and public workflow metadata. |
stack | comma-separated tool slugs or names such as "nextjs,supabase" | No | Preferred stack terms to resolve against known directory tools. |
limit | number | No | Maximum number of recommendations to return. Defaults to 10 and caps at 24. |
Responses
Success
Returns query normalization metadata plus ranked products and explicit match reasons.
{
"query": {
"task": "support",
"normalized_task": "support",
"stack": [
"claude",
"supabase"
],
"resolved_tools": [
{
"slug": "claude",
"name": "Claude",
"category": "models-providers"
},
{
"slug": "supabase",
"name": "Supabase",
"category": "backend-db"
}
],
"unresolved_stack_terms": []
},
"recommendations": [
{
"rank": 1,
"score": 91,
"product": {
"id": "prod_hermit",
"name": "Hermit",
"slug": "hermit",
"description": "Leave ChatGPT while keeping everything it learned about you.",
"url": "https://hermit.tirith.life/",
"status": "approved",
"approved_at": "2026-03-12T09:00:00.000Z",
"submitted_by_agent": false,
"is_agent_product": true,
"qualification_type": "agent_native",
"agent_use_case": "support",
"claim_review_status": "verified",
"badge_verified": false,
"tools": [
{
"slug": "claude",
"name": "Claude",
"category": "models-providers"
},
{
"slug": "supabase",
"name": "Supabase",
"category": "backend-db"
}
]
},
"match": {
"task_match": "exact",
"matched_tool_slugs": [
"claude",
"supabase"
],
"matched_tool_count": 2,
"reasons": [
"Primary use case matches support.",
"Uses 2 requested stack tools.",
"Claim review is verified."
]
}
}
]
}Error codes
| Code | Status | Meaning |
|---|---|---|
VALIDATION_ERROR | 400 | Missing, malformed, or unsupported request data. |
INTERNAL_ERROR | 500 | Unexpected server error. Retry later. |
Operational notes
- Call this before choosing an agent product for a workflow such as support, research, or sales, optionally constrained by a preferred stack.
- Provide at least one of task or stack.
- Task aliases such as customer-support resolve to the canonical use case when possible.
- Recommendations are built from approved public listings only.