Use the public API when your agent needs to submit a real product into the directory, attach an Agent Directory claim, or inspect the approved catalog programmatically.
Recommended workflow
1. Discover valid tools first
Do not guess tool identifiers. Fetch the current tool inventory first and map your product stack to the returned tool_slugs.
2. Submit the product
Send a single JSON payload to POST /api/v1/submit. The API accepts only free-tier submissions and every accepted submission enters pending review first. Agent Directory claim fields are optional but must be complete when provided.
3. Poll review status
Use the returned slug with GET /api/v1/products/:slug?email=... to check whether a pending submission is still in review. The submit response also returns owner_claim, which tells you whether the submitter inbox still needs email verification as the first ownership proof.
4. Browse the approved catalog
Once you need discovery or verification, use GET /api/v1/products and GET /api/v1/search.
Integration expectations
- Use the canonical product homepage, not a docs page or announcement URL.
- Keep
descriptionat or under 240 characters. - Prefer
tool_slugsovertool_ids. - Expect manual review before the listing is public.
- Poll
review_status_urlno more than once every 300 seconds unless a response gives stricter guidance. - Treat rate limits as part of the public contract.
GET
/api/v1/toolsUse this endpoint as the source of truth for valid tool slugs before calling the submit endpoint.
Auth
No API keys. No account auth. Public JSON endpoints only.
Review model
Read-only endpoint. No review-state implications.
Cache
5 minute revalidation.
Example request
curl https://www.madewithstack.com/api/v1/tools
Responses
200
Success
Returns the ordered tool inventory used by the submission flow.
{
"tools": [
{
"slug": "claude",
"name": "Claude",
"category": "models-providers",
"description": "Model provider for conversational and agent workflows."
},
{
"slug": "supabase",
"name": "Supabase",
"category": "backend-db",
"description": "Postgres backend, auth, and storage platform."
}
]
}Error codes
| Code | Status | Meaning |
|---|---|---|
INTERNAL_ERROR | 500 | Unexpected server error. Retry later. |
Operational notes
- Call this before building a submission payload or when refreshing a local tool cache.
- Use tool_slugs from this endpoint instead of hardcoding UUIDs.
- Responses are cached for 5 minutes.
POST
/api/v1/submitThis is the agent-facing write endpoint for creating pending submissions without using the browser form.
Auth
No API keys. No account auth. Public JSON endpoints only.
Review model
Submit is write-only into the manual review queue. Listings do not publish instantly.
Cache
No caching. Write endpoint with separate IP and email rate-limit buckets.
Example request
curl -X POST https://www.madewithstack.com/api/v1/submit \
-H "Content-Type: application/json" \
-d '{
"name": "AgentFlow",
"url": "https://agentflow.dev",
"description": "Workflow automation for multi-agent pipelines.",
"email": "founder@agentflow.dev",
"tool_slugs": ["langchain", "claude"],
"qualification_type": "agent_built",
"agent_use_case": "operations",
"qualification_statement": "Agents handled substantial parts of the workflow and build process.",
"workflow_summary": "The product routes operational work through an agentic workflow.",
"agent_tools_used": ["Cursor", "Claude"],
"supporting_links": ["https://agentflow.dev/docs"],
"founder_name": "Ada Smith",
"audience_tags": ["b2b", "for-developers"]
}'Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Product name. |
url | absolute http/https URL | Yes | Canonical product homepage URL. |
description | string | Yes | Short description. Maximum 240 characters. |
email | string | Yes | Submitter email used for review updates and pending-status checks. |
tool_slugs | string[] | No | Preferred tool identifiers. Discover valid values from GET /api/v1/tools. |
tool_ids | UUID[] | No | Alternative to tool_slugs. Every value must be a valid UUID string. |
custom_tools | string[] | No | Custom tool names. Maximum 5 entries, each 40 characters or less. |
founder_name | string | No | Founder or team name. |
founder_twitter | string | No | X/Twitter handle. |
favicon_url | absolute http/https URL | No | Manual logo override. |
screenshot_url | absolute http/https URL | No | Manual screenshot override. |
audience_tags | ("for-developers" | "for-founders" | "b2b" | "consumer")[] | No | Optional audience tags. |
qualification_type | "agent_native" | "agent_built" | "agentic_workflow" | No | Optional Agent Directory qualification type. If provided, the related claim fields become required. |
agent_use_case | "support" | "research" | "operations" | "sales" | "voice" | "browser_automation" | No | Primary use case for Agent Directory review. |
qualification_statement | string | No | Short public justification for Agent Directory eligibility. |
workflow_summary | string | No | How the agent or agentic workflow is central to the product. |
agent_tools_used | string[] | No | Named agent-building tools used in the product or build process. |
supporting_links | string[] | No | Supporting public links reviewers can inspect for the claim. |
referral_code | string | No | Optional referral code from an existing listing. |
Responses
201
Submission created
The submission was accepted into pending review. The product is not public yet.
{
"success": true,
"slug": "agentflow",
"receiptSent": true,
"review_status_url": "https://www.madewithstack.com/api/v1/products/agentflow?email=founder%40agentflow.dev",
"owner_claim": {
"email": "founder@agentflow.dev",
"status": "unverified",
"verification_email_sent": true
},
"claim_status": "submitted",
"claim_eligibility": "agent_directory",
"next_action_code": "UNDER_EDITORIAL_REVIEW"
}Error codes
| Code | Status | Meaning |
|---|---|---|
VALIDATION_ERROR | 400 | Missing, malformed, or unsupported request data. |
INVALID_TOOL_SLUGS | 400 | One or more submitted tool slugs are not present in the directory. |
DUPLICATE_DOMAIN | 409 | A product with the same normalized domain already exists. |
RATE_LIMITED | 429 | The request exceeded the public API rate limit window. |
INTERNAL_ERROR | 500 | Unexpected server error. Retry later. |
Operational notes
- Call this when you have a valid product homepage, a short description, a submitter email, and stack metadata ready for review.
- At least one of tool_slugs, tool_ids, or custom_tools must be non-empty.
- If qualification_type is provided, agent_use_case, qualification_statement, workflow_summary, agent_tools_used, and supporting_links are required.
- tool_slugs is preferred over tool_ids.
- API submissions are free-tier only. paid_fast_track is not exposed through the API.
- Listings require manual approval before they appear in the public catalog.
- Use review_status_url from the response to poll review, claim state, and badge availability.
- Recommended polling interval is 300 seconds, with longer backoff after repeated unchanged responses.
- 429 responses include a Retry-After header in seconds.
GET
/api/v1/products/:slugThis is the status-check endpoint for programmatic submissions and the canonical read endpoint for approved product details and public badge verification state.
Auth
No API keys. No account auth. Public JSON endpoints only.
Review model
Pending status is visible only to the original submitter email. Approved status is public.
Cache
Dynamic server response.
Example request
curl "https://www.madewithstack.com/api/v1/products/agentflow?email=founder@agentflow.dev"
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
email | string | No | Required only when checking the status of a pending submission. Must match the submitter email. |
Responses
200
Approved listing
Returns the richer approved product detail object plus a machine-readable public badge-status payload when the slug is already public.
{
"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"
}
],
"overview": "string | null",
"editorial_summary": "string | null",
"trust": {
"review_model": "\"manual\"",
"source_kind": "\"curated\" | \"user_submission\" | \"other\"",
"source_quality": "\"curated_evidence\" | \"reviewed_with_evidence\" | \"manual_review_only\"",
"source_url": "string",
"verified_at": "string | null",
"public_note": "string | null",
"evidence": [
{
"type": "string",
"url": "string"
}
]
}
},
"badge": {
"available": "boolean",
"image_url": "string",
"verification": {
"status": "\"pending_approval\" | \"awaiting_verification\" | \"verified\" | \"paid_dofollow\"",
"is_dofollow": "boolean",
"requires_badge_install": "boolean",
"requires_manual_review": "boolean",
"detail": "string"
}
},
"claim_status": "verified",
"claim_eligibility": "agent_directory",
"next_action_code": "APPROVED_FOR_AGENT_DIRECTORY"
}200
Pending submission
Returns minimal pending-state data plus badge availability state when the slug exists in pending status and the submitter email matches.
{
"product": {
"slug": "agentflow",
"name": "AgentFlow",
"status": "pending",
"created_at": "2026-03-11T09:15:00.000Z"
},
"badge": {
"available": "boolean",
"image_url": "string",
"verification": {
"status": "\"pending_approval\" | \"awaiting_verification\" | \"verified\" | \"paid_dofollow\"",
"is_dofollow": "boolean",
"requires_badge_install": "boolean",
"requires_manual_review": "boolean",
"detail": "string"
}
},
"claim_status": "submitted",
"claim_eligibility": "agent_directory",
"next_action_code": "UNDER_EDITORIAL_REVIEW"
}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 after submitting to poll pending review status, or call it without email when reading an approved listing and its public badge state.
- If the product is not approved and no matching submitter email is provided, the endpoint returns 404.
- Approved listings do not require email verification.
- Approved responses include editorial_summary, overview, and a public-safe trust object derived from the primary review source.
- Public badge data only describes verification state. Owner-only embed code stays in the approval email and launch kit flow.
GET
/api/v1/productsUse this endpoint to inspect the public catalog, power integrations, or fetch filtered inventory for a specific stack, audience, or agent layer.
Auth
No API keys. No account auth. Public JSON endpoints only.
Review model
Read-only endpoint over approved catalog data.
Cache
Dynamic server response backed by the approved catalog query layer.
Example request
curl "https://www.madewithstack.com/api/v1/products?limit=10&sort=newest&is_agent=true"
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
offset | number | No | Pagination offset. Defaults to 0. |
limit | number | No | Page size from 1 to 48. Defaults to 24. |
sort | "newest" | "popular" | No | Sort order. Defaults to "newest". |
category | tool category slug | No | Filter by tool category. |
audience | "for-developers" | "for-founders" | "b2b" | "consumer" | "all" | No | Filter by audience tag. |
tool | tool slug | No | Filter by a specific tool slug such as supabase. |
is_agent | "true" | No | Return only Agent Directory listings. |
qualification_type | "agent_native" | "agent_built" | "agentic_workflow" | No | Filter Agent Directory results by qualification type. |
claim_status | "claim_submitted" | "claim_verified" | No | Filter Agent Directory results by public claim-review state. |
agent_use_case | "support" | "research" | "operations" | "sales" | "voice" | "browser_automation" | No | Filter Agent Directory results by primary use case. |
Responses
200
Success
Returns a page of approved listings only.
{
"products": [
{
"id": "prod_123",
"name": "AgentFlow",
"slug": "agentflow",
"description": "Workflow automation for multi-agent pipelines.",
"url": "https://agentflow.dev",
"favicon_url": "https://agentflow.dev/icon.png",
"founder_name": "Ada Smith",
"founder_twitter": "ada_smith",
"founder_profile_slug": "ada-smith",
"launch_date": null,
"status": "approved",
"created_at": "2026-03-10T08:00:00.000Z",
"approved_at": "2026-03-11T09:15:00.000Z",
"view_count": 42,
"is_featured": false,
"featured_rank": 100,
"screenshot_url": "https://agentflow.dev/shot.png",
"submission_tier": "free",
"review_priority": 100,
"audience_tags": [
"b2b",
"for-developers"
],
"badge_verified": false,
"is_agent_product": true,
"qualification_type": "agent_native",
"agent_use_case": "operations",
"qualification_statement": "Agent-led workflow is central to the product.",
"workflow_summary": "The product uses an agentic workflow as the main user experience.",
"agent_tools_used": [
"Claude",
"LangChain"
],
"supporting_links": [
"https://agentflow.dev/docs"
],
"claim_review_status": "verified",
"claim_reviewed_at": "2026-03-11T09:20:00.000Z",
"claim_review_notes": null,
"claim_verified_by": "editor@madewithstack.com",
"claim_evidence_summary": "Reviewed against public docs and product workflow pages.",
"tools": [
{
"id": "tool_1",
"name": "Claude",
"slug": "claude",
"description": "Model provider",
"icon_url": null,
"category": "models-providers",
"product_count": 12,
"created_at": "2026-03-01T00:00:00.000Z"
}
]
}
],
"total": 1,
"offset": 0,
"limit": 24,
"hasMore": false
}Error codes
| Code | Status | Meaning |
|---|---|---|
INTERNAL_ERROR | 500 | Unexpected server error. Retry later. |
Operational notes
- Call this after approval, when building discovery experiences, or when verifying what the directory already contains.
- This endpoint returns approved listings only.
- Filters can be combined.