{"openapi":"3.1.0","info":{"title":"AppCorpus Public API","version":"3.0.0","description":"Read-only JSON API over the AppCorpus catalog of current App Store and Google Play apps. The same data powers the public HTML pages and the MCP server at /mcp."},"servers":[{"url":"https://appcorpus.com"}],"paths":{"/api/v3/search":{"get":{"operationId":"search","summary":"Search the catalog by name, developer or task.","tags":["taxonomy"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"What to look for: an app name, a developer, or what the app does."},{"name":"market","in":"query","required":false,"schema":{"type":"string","default":"us","enum":["us","gb","de","es"]},"description":"Country storefront (us/gb English, de German, es Spanish)."},{"name":"store","in":"query","required":false,"schema":{"type":"string","enum":["apple","gplay","both"]},"description":"Restrict to one store, or apps present in both."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["iphone","ipad","mac","watch","android"]}},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"AppCorpus category slug."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["relevance","popular","rating","ratings","updated","new"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":12}}],"responses":{"200":{"description":"Ranked app cards with search_mode, freshness and scope (SPEC-07 §4.2).","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v3/apps/search":{"get":{"operationId":"searchApps","summary":"Search the catalog by name, developer or task.","tags":["apps"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"What to look for: an app name, a developer, or what the app does."},{"name":"market","in":"query","required":false,"schema":{"type":"string","default":"us","enum":["us","gb","de","es"]},"description":"Country storefront (us/gb English, de German, es Spanish)."},{"name":"store","in":"query","required":false,"schema":{"type":"string","enum":["apple","gplay","both"]},"description":"Restrict to one store, or apps present in both."},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["iphone","ipad","mac","watch","android"]}},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"AppCorpus category slug."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["relevance","popular","rating","ratings","updated","new"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":12}}],"responses":{"200":{"description":"Ranked app cards with search_mode, freshness and scope (SPEC-07 §4.2).","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v3/apps":{"get":{"operationId":"listApps","summary":"Browse the catalog with filters and pagination.","tags":["apps"],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"market","in":"query","required":false,"schema":{"type":"string","default":"us","enum":["us","gb","de","es"]},"description":"Country storefront (us/gb English, de German, es Spanish)."},{"name":"store","in":"query","required":false,"schema":{"type":"string","enum":["apple","gplay","both"]}},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["iphone","ipad","mac","watch","android"]}},{"name":"category","in":"query","required":false,"schema":{"type":"string"}},{"name":"use_case","in":"query","required":false,"schema":{"type":"string"}},{"name":"pricing","in":"query","required":false,"schema":{"type":"string","enum":["free","paid","subscription","iap"]}},{"name":"rating_gte","in":"query","required":false,"schema":{"type":"number","enum":[4.5,4.0,3.5,3.0]}},{"name":"rating_count_gte","in":"query","required":false,"schema":{"type":"integer","enum":[1000,500,100,50,10]}},{"name":"updated","in":"query","required":false,"schema":{"type":"string","enum":["30d","90d","180d"]}},{"name":"quality","in":"query","required":false,"schema":{"type":"string","enum":["store","enriched","reviewed"]}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["relevance","popular","rating","ratings","updated","new"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":60,"default":24}}],"responses":{"200":{"description":"A page of app cards.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v3/apps/{app_id}":{"get":{"operationId":"getApp","summary":"Full catalog card of one app (the SSR app page as JSON).","tags":["apps"],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string"},"description":"Numeric app id, optionally slug-prefixed."},{"name":"market","in":"query","required":false,"schema":{"type":"string","default":"us","enum":["us","gb","de","es"]},"description":"Country storefront (us/gb English, de German, es Spanish)."}],"responses":{"200":{"description":"The app resource built from PublicAppPageDTO.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v3/apps/{app_id}/{slice}":{"get":{"operationId":"getAppSlice","summary":"One DTO block of an app card (screens, features, pricing, reviews, changes, evidence, feature_events).","tags":["apps"],"parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string"},"description":"Numeric app id, optionally slug-prefixed."},{"name":"slice","in":"path","required":true,"schema":{"type":"string"},"description":"DTO block name."},{"name":"market","in":"query","required":false,"schema":{"type":"string","default":"us","enum":["us","gb","de","es"]},"description":"Country storefront (us/gb English, de German, es Spanish)."}],"responses":{"200":{"description":"A single block of the app resource.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v3/categories":{"get":{"operationId":"listCategories","summary":"List AppCorpus categories.","tags":["taxonomy"],"parameters":[],"responses":{"200":{"description":"All active categories with app counts.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v3/categories/{category_id}":{"get":{"operationId":"getCategory","summary":"One category with its top apps.","tags":["taxonomy"],"parameters":[{"name":"category_id","in":"path","required":true,"schema":{"type":"string"},"description":"Category slug."},{"name":"market","in":"query","required":false,"schema":{"type":"string","default":"us","enum":["us","gb","de","es"]},"description":"Country storefront (us/gb English, de German, es Spanish)."}],"responses":{"200":{"description":"JSON resource","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v3/use-cases":{"get":{"operationId":"listUseCases","summary":"List AppCorpus use cases.","tags":["taxonomy"],"parameters":[],"responses":{"200":{"description":"All active use cases with app counts.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v3/use-cases/{use_case_id}":{"get":{"operationId":"getUseCase","summary":"One use case with evaluated candidate apps.","tags":["taxonomy"],"parameters":[{"name":"use_case_id","in":"path","required":true,"schema":{"type":"string"},"description":"Use-case slug."},{"name":"market","in":"query","required":false,"schema":{"type":"string","default":"us","enum":["us","gb","de","es"]},"description":"Country storefront (us/gb English, de German, es Spanish)."}],"responses":{"200":{"description":"JSON resource","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v3/capabilities":{"get":{"operationId":"listCapabilities","summary":"List AppCorpus capability dictionary entries.","tags":["taxonomy"],"parameters":[],"responses":{"200":{"description":"All active capabilities with published app counts.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v3/capabilities/{capability_id}":{"get":{"operationId":"getCapability","summary":"One capability with definition and use-case links.","tags":["taxonomy"],"parameters":[{"name":"capability_id","in":"path","required":true,"schema":{"type":"string"},"description":"Capability id (snake_case)."}],"responses":{"200":{"description":"JSON resource","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v3/developers/{developer_id}":{"get":{"operationId":"getDeveloper","summary":"One developer with their current apps.","tags":["taxonomy"],"parameters":[{"name":"developer_id","in":"path","required":true,"schema":{"type":"string"},"description":"Developer slug or {slug}-{id} token."},{"name":"market","in":"query","required":false,"schema":{"type":"string","default":"us","enum":["us","gb","de","es"]},"description":"Country storefront (us/gb English, de German, es Spanish)."}],"responses":{"200":{"description":"JSON resource","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v3/health/public":{"get":{"operationId":"healthPublic","summary":"Public catalog health (status, corpus size, last import).","tags":["taxonomy"],"parameters":[],"responses":{"200":{"description":"Coarse public health for /agents and uptime checks.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"details":{"type":"object"}},"required":["code","message"]}},"required":["error"]}}}}