{ "openapi": "3.1.0", "info": { "title": "Jev AI Use Cases API", "version": "1.0.0", "description": "Public directory search, agent tools, and moderated submission API." }, "servers": [ { "url": "https://jevaiusecases.com" } ], "paths": { "/api/health": { "get": { "summary": "Service health", "responses": { "200": { "description": "Healthy service", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } } } } } } } } }, "/api/use-cases": { "get": { "summary": "Search and filter use cases", "parameters": [ { "name": "q", "in": "query", "description": "Text search", "required": false, "schema": { "type": "string" } }, { "name": "grade", "in": "query", "description": "Grade key", "required": false, "schema": { "type": "string", "enum": [ "S", "A", "B", "C", "X", "?" ] } }, { "name": "vertical", "in": "query", "description": "Vertical key", "required": false, "schema": { "type": "string", "enum": [ "cross_industry", "medical_aesthetic", "healthcare_dental", "legal", "home_local_services", "real_estate", "agency_media_creator", "ecommerce_retail", "saas_tech", "finance_insurance", "education", "hospitality_travel_events", "staffing_recruiting", "industrial_energy_ag", "logistics_supply", "government_nonprofit", "games_entertainment", "research_science", "insufficient_context" ] } }, { "name": "function", "in": "query", "description": "Function key", "required": false, "schema": { "type": "string", "enum": [ "personalization_cro", "ads", "seo_ai_search", "local_reputation", "social_creator", "email_crm", "content_brand", "sales", "support_cx", "ecommerce", "health_admin", "legal_finance", "ops_hr", "agents_dev", "research_edu", "creative_industry", "knowledge_work", "other" ] } }, { "name": "status", "in": "query", "description": "Evidence status", "required": false, "schema": { "type": "string", "enum": [ "seen", "idea" ] } }, { "name": "limit", "in": "query", "description": "Page size, maximum 200", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "offset", "in": "query", "description": "Zero-based offset", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Matching use cases", "content": { "application/json": { "schema": { "type": "object", "required": [ "total", "limit", "offset", "results" ], "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "description": "A graded typed-decision use case", "properties": { "slug": { "type": "string", "description": "Stable URL slug" }, "grade": { "type": "string", "description": "S, A, B, C, X, or ?", "enum": [ "S", "A", "B", "C", "X", "?" ] }, "title": { "type": "string", "description": "Use case title" }, "description": { "type": "string", "description": "Decision description" }, "vertical": { "type": "string", "description": "Vertical taxonomy key", "enum": [ "cross_industry", "medical_aesthetic", "healthcare_dental", "legal", "home_local_services", "real_estate", "agency_media_creator", "ecommerce_retail", "saas_tech", "finance_insurance", "education", "hospitality_travel_events", "staffing_recruiting", "industrial_energy_ag", "logistics_supply", "government_nonprofit", "games_entertainment", "research_science", "insufficient_context" ] }, "function": { "type": "string", "description": "Function taxonomy key", "enum": [ "personalization_cro", "ads", "seo_ai_search", "local_reputation", "social_creator", "email_crm", "content_brand", "sales", "support_cx", "ecommerce", "health_admin", "legal_finance", "ops_hr", "agents_dev", "research_edu", "creative_industry", "knowledge_work", "other" ] }, "status": { "type": "string", "description": "Seen in evidence or proposed idea", "enum": [ "seen", "idea" ] }, "volume": { "type": "string", "description": "Estimated volume" }, "value": { "type": "string", "description": "Estimated value" }, "risk": { "type": "string", "description": "Risk level" }, "evidence": { "type": [ "string", "null" ], "description": "Evidence summary when available" }, "flags": { "type": "array", "items": { "type": "string" } }, "source_url": { "type": [ "string", "null" ], "format": "uri" }, "score": { "type": "number", "description": "Ranking score" } } } } } } } } } } } }, "/api/use-cases/{slug}": { "get": { "summary": "Get one use case", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Use case", "content": { "application/json": { "schema": { "type": "object", "description": "A graded typed-decision use case", "properties": { "slug": { "type": "string", "description": "Stable URL slug" }, "grade": { "type": "string", "description": "S, A, B, C, X, or ?", "enum": [ "S", "A", "B", "C", "X", "?" ] }, "title": { "type": "string", "description": "Use case title" }, "description": { "type": "string", "description": "Decision description" }, "vertical": { "type": "string", "description": "Vertical taxonomy key", "enum": [ "cross_industry", "medical_aesthetic", "healthcare_dental", "legal", "home_local_services", "real_estate", "agency_media_creator", "ecommerce_retail", "saas_tech", "finance_insurance", "education", "hospitality_travel_events", "staffing_recruiting", "industrial_energy_ag", "logistics_supply", "government_nonprofit", "games_entertainment", "research_science", "insufficient_context" ] }, "function": { "type": "string", "description": "Function taxonomy key", "enum": [ "personalization_cro", "ads", "seo_ai_search", "local_reputation", "social_creator", "email_crm", "content_brand", "sales", "support_cx", "ecommerce", "health_admin", "legal_finance", "ops_hr", "agents_dev", "research_edu", "creative_industry", "knowledge_work", "other" ] }, "status": { "type": "string", "description": "Seen in evidence or proposed idea", "enum": [ "seen", "idea" ] }, "volume": { "type": "string", "description": "Estimated volume" }, "value": { "type": "string", "description": "Estimated value" }, "risk": { "type": "string", "description": "Risk level" }, "evidence": { "type": [ "string", "null" ], "description": "Evidence summary when available" }, "flags": { "type": "array", "items": { "type": "string" } }, "source_url": { "type": [ "string", "null" ], "format": "uri" }, "score": { "type": "number", "description": "Ranking score" } } } } } }, "404": { "description": "Not found" } } } }, "/api/use-cases.json": { "get": { "summary": "Download complete static dataset", "responses": { "200": { "description": "Complete dataset", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "A graded typed-decision use case", "properties": { "slug": { "type": "string", "description": "Stable URL slug" }, "grade": { "type": "string", "description": "S, A, B, C, X, or ?", "enum": [ "S", "A", "B", "C", "X", "?" ] }, "title": { "type": "string", "description": "Use case title" }, "description": { "type": "string", "description": "Decision description" }, "vertical": { "type": "string", "description": "Vertical taxonomy key", "enum": [ "cross_industry", "medical_aesthetic", "healthcare_dental", "legal", "home_local_services", "real_estate", "agency_media_creator", "ecommerce_retail", "saas_tech", "finance_insurance", "education", "hospitality_travel_events", "staffing_recruiting", "industrial_energy_ag", "logistics_supply", "government_nonprofit", "games_entertainment", "research_science", "insufficient_context" ] }, "function": { "type": "string", "description": "Function taxonomy key", "enum": [ "personalization_cro", "ads", "seo_ai_search", "local_reputation", "social_creator", "email_crm", "content_brand", "sales", "support_cx", "ecommerce", "health_admin", "legal_finance", "ops_hr", "agents_dev", "research_edu", "creative_industry", "knowledge_work", "other" ] }, "status": { "type": "string", "description": "Seen in evidence or proposed idea", "enum": [ "seen", "idea" ] }, "volume": { "type": "string", "description": "Estimated volume" }, "value": { "type": "string", "description": "Estimated value" }, "risk": { "type": "string", "description": "Risk level" }, "evidence": { "type": [ "string", "null" ], "description": "Evidence summary when available" }, "flags": { "type": "array", "items": { "type": "string" } }, "source_url": { "type": [ "string", "null" ], "format": "uri" }, "score": { "type": "number", "description": "Ranking score" } } } } } } } } } }, "/api/taxonomy.json": { "get": { "summary": "Download taxonomy", "responses": { "200": { "description": "Vertical, function, and grade definitions", "content": { "application/json": { "schema": { "type": "object", "properties": { "verticals": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "functions": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "grades": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } } } }, "/api/challenge": { "get": { "summary": "Get agent proof-of-work challenge", "responses": { "200": { "description": "A short-lived challenge", "content": { "application/json": { "schema": { "type": "object", "required": [ "challenge", "difficulty", "algorithm", "expires_at", "instructions" ], "properties": { "challenge": { "type": "string" }, "difficulty": { "type": "integer", "description": "Required leading zero bits" }, "algorithm": { "type": "string", "example": "sha256" }, "expires_at": { "type": "string", "format": "date-time" }, "instructions": { "type": "string" } } } } } } } } }, "/api/submissions": { "post": { "summary": "Submit a new use case for moderation", "description": "No account. Supply either a Turnstile token or a valid proof of work. Limit: 5/hour and 20/day per IP hash.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "description", "vertical", "function", "decision_type" ], "properties": { "title": { "type": "string", "description": "Concise decision title", "minLength": 8, "maxLength": 120 }, "description": { "type": "string", "description": "Explain the typed decision and where it recurs", "minLength": 40, "maxLength": 1000 }, "vertical": { "type": "string", "description": "Vertical taxonomy key", "enum": [ "cross_industry", "medical_aesthetic", "healthcare_dental", "legal", "home_local_services", "real_estate", "agency_media_creator", "ecommerce_retail", "saas_tech", "finance_insurance", "education", "hospitality_travel_events", "staffing_recruiting", "industrial_energy_ag", "logistics_supply", "government_nonprofit", "games_entertainment", "research_science", "insufficient_context" ] }, "function": { "type": "string", "description": "Function taxonomy key", "enum": [ "personalization_cro", "ads", "seo_ai_search", "local_reputation", "social_creator", "email_crm", "content_brand", "sales", "support_cx", "ecommerce", "health_admin", "legal_finance", "ops_hr", "agents_dev", "research_edu", "creative_industry", "knowledge_work", "other" ] }, "decision_type": { "type": "string", "description": "Shape of the decision", "enum": [ "yes_no", "choice", "score" ] }, "example_input": { "type": "string", "description": "Optional example input" }, "source_url": { "type": "string", "format": "uri", "description": "Optional http(s) source" }, "submitter_name": { "type": "string", "description": "Optional name" }, "submitter_contact": { "type": "string", "description": "Optional contact" }, "agent_name": { "type": "string", "description": "Optional agent name; informational only" }, "website": { "type": "string", "description": "Honeypot; must be empty", "maxLength": 0 }, "turnstile_token": { "type": "string", "description": "Turnstile token for human submissions" }, "pow": { "type": "object", "description": "Agent proof of work from GET /api/challenge", "required": [ "challenge", "nonce" ], "properties": { "challenge": { "type": "string" }, "nonce": { "type": "string" } } } } } } } }, "responses": { "202": { "description": "Queued for moderation", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status", "message" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "example": "pending" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid submission or proof" }, "409": { "description": "Duplicate submission" }, "429": { "description": "Rate limited" } } } }, "/api/submissions/{id}": { "get": { "summary": "Check submission status", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Submission status", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Not found" } } } }, "/mcp": { "post": { "summary": "Stateless MCP Streamable HTTP JSON-RPC endpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "method": { "type": "string" }, "params": { "type": "object" }, "id": { "type": [ "string", "integer", "null" ] } } } } } }, "responses": { "200": { "description": "MCP JSON-RPC response", "content": { "application/json": { "schema": { "type": "object" } } } } } } } } }