Use this endpoint when an agent needs ranked directory candidates instead of a raw catalog page.
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.
GET
/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=customer-support&stack=nextjs,supabase"
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
200
Success
Returns query normalization metadata plus ranked products and explicit match reasons.
{
"query": {
"task": "string | null",
"normalized_task": "\"support\" | \"research\" | \"operations\" | \"sales\" | \"voice\" | \"browser_automation\" | null",
"stack": [
"string"
],
"resolved_tools": [
{
"slug": "string",
"name": "string",
"category": "string"
}
],
"unresolved_stack_terms": [
"string"
]
},
"recommendations": [
{
"rank": "number",
"score": "number",
"product": {
"id": "string",
"name": "string",
"slug": "string",
"description": "string",
"url": "string",
"favicon_url": "string | null",
"founder_name": "string | null",
"founder_twitter": "string | null",
"founder_profile_slug": "string | null",
"launch_date": "string | null",
"status": "\"approved\"",
"created_at": "string",
"approved_at": "string | null",
"view_count": "number",
"is_featured": "boolean",
"featured_rank": "number",
"screenshot_url": "string | null",
"submission_tier": "\"free\" | \"paid_fast_track\"",
"review_priority": "number",
"audience_tags": [
"\"for-developers\" | \"for-founders\" | \"b2b\" | \"consumer\""
],
"badge_verified": "boolean",
"is_agent_product": "boolean",
"qualification_type": "\"agent_native\" | \"agent_built\" | \"agentic_workflow\" | null",
"agent_use_case": "\"support\" | \"research\" | \"operations\" | \"sales\" | \"voice\" | \"browser_automation\" | null",
"qualification_statement": "string | null",
"workflow_summary": "string | null",
"agent_tools_used": "string[]",
"supporting_links": "string[]",
"claim_review_status": "\"submitted\" | \"verified\" | \"not_verified\" | \"needs_revision\" | null",
"claim_reviewed_at": "string | null",
"claim_review_notes": "string | null",
"claim_verified_by": "string | null",
"claim_evidence_summary": "string | null",
"tools": [
{
"id": "string",
"name": "string",
"slug": "string",
"description": "string | null",
"icon_url": "string | null",
"category": "string",
"product_count": "number",
"created_at": "string"
}
]
},
"match": {
"task_match": "\"exact\" | \"text\" | \"none\"",
"matched_tool_slugs": [
"string"
],
"matched_tool_count": "number",
"reasons": [
"string"
]
}
}
]
}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.