{"openapi":"3.0.3","info":{"title":"CodeJa API","version":"1.0.0","description":"Public REST & Agent API for CodeJa - Interactive Java & Spring Boot learning platform. Provides access to courses, masters, projects, AI code diagnostics, and Model Context Protocol (MCP) server endpoints.","contact":{"name":"CodeJa Support","email":"ricardo@programandoenjava.com","url":"https://codeja.dev/developers"},"license":{"name":"Proprietary","url":"https://codeja.dev/tos"}},"servers":[{"url":"https://codeja.dev","description":"CodeJa Production Server"}],"paths":{"/api/courses":{"get":{"summary":"List Courses","description":"Retrieves a list of available courses on CodeJa, including titles, descriptions, slugs, lesson counts, and free/pro access status.","operationId":"listCourses","tags":["Courses"],"responses":{"200":{"description":"A list of course objects.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Course"}}}}}}}},"/api/courses/{slug}":{"get":{"summary":"Get Course Details","description":"Retrieves detailed information for a specific course by its slug, including sections and lesson structures.","operationId":"getCourseBySlug","tags":["Courses"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The unique URL slug of the course (e.g., 'fundamentos-java').","schema":{"type":"string"}}],"responses":{"200":{"description":"Course detailed object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Course"}}}},"404":{"description":"Course not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/masters":{"get":{"summary":"List Active Master Programs","description":"Retrieves all active master specialization programs (e.g., Master AI Engineer Java, Master Arquitecto Java IA).","operationId":"listMasters","tags":["Masters"],"responses":{"200":{"description":"List of master programs.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MasterProgram"}}}}}}}},"/api/ask":{"post":{"summary":"Ask AI Assistant / NL Query","description":"Submits a natural language query about Java, Spring Boot, or CodeJa platform courses to receive AI-generated explanations and search results.","operationId":"askQuery","tags":["AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Natural language query or question about Java/Spring Boot.","example":"¿Cómo configurar Spring Security 6 con JWT?"}}}}}},"responses":{"200":{"description":"AI response with search results and detailed answer.","content":{"application/json":{"schema":{"type":"object","properties":{"answer":{"type":"string","description":"AI-generated Markdown answer."},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"}}}}}}}}},"429":{"description":"Rate limit exceeded (30 requests per minute).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/java/analyze":{"post":{"summary":"Analyze Java Code & Diagnostics","description":"Analyzes Java or Spring Boot source code for syntax errors, architectural smells, security bugs, or runtime exceptions.","operationId":"analyzeJavaCode","tags":["AI","Code Analysis"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"The Java source code snippet to analyze.","example":"public class Main { public static void main(String[] args) { System.out.println(\"Hello World\"); } }"},"lastError":{"type":"string","description":"Optional compiler error message or stack trace."},"lastOutput":{"type":"string","description":"Optional execution output text."}}}}}},"responses":{"200":{"description":"Structured diagnostic and code review feedback.","content":{"application/json":{"schema":{"type":"object","properties":{"analysis":{"type":"string","description":"Markdown review feedback and recommendations."}}}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/mcp":{"post":{"summary":"Model Context Protocol JSON-RPC Endpoint","description":"Executes Model Context Protocol (MCP) JSON-RPC 2.0 requests (initialize, ping, tools/list, tools/call) for autonomous agent integration.","operationId":"mcpRpc","tags":["MCP"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"example":"2.0"},"id":{"type":"string","nullable":true,"example":"1"},"method":{"type":"string","description":"MCP protocol method (e.g. 'initialize', 'ping', 'tools/list', 'tools/call').","example":"tools/list"},"params":{"type":"object","description":"Optional RPC parameters."}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response object.","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"type":"string","nullable":true},"result":{"type":"object"},"error":{"type":"object"}}}}}}}},"get":{"summary":"MCP Protocol Server Discovery","description":"Returns MCP server status, capabilities, and tools metadata.","operationId":"mcpDiscovery","tags":["MCP"],"responses":{"200":{"description":"MCP Server capabilities and status.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"server":{"type":"string","example":"CodeJa Admin MCP Server"},"version":{"type":"string","example":"1.0.0"},"toolsCount":{"type":"number","example":22}}}}}}}}},"/api/users/{id}":{"get":{"summary":"Get Public User Profile","description":"Retrieves public profile information, completed courses, and skills for a user.","operationId":"getUserProfile","tags":["Users"],"parameters":[{"name":"id","in":"path","required":true,"description":"User ID or public profile identifier.","schema":{"type":"string"}}],"responses":{"200":{"description":"User public profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfile"}}}},"404":{"description":"User profile not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"Course":{"type":"object","required":["id","title","slug","description"],"properties":{"id":{"type":"string","example":"crs_123"},"title":{"type":"string","example":"Fundamentos de Java"},"slug":{"type":"string","example":"fundamentos-java"},"description":{"type":"string","example":"Curso de sintaxis, POO y colecciones en Java."},"summary":{"type":"string","example":"Aprende Java desde cero."},"isFree":{"type":"boolean","example":true},"image":{"type":"string","example":"https://codeja.dev/images/courses/java.jpg"}}},"MasterProgram":{"type":"object","required":["id","title","slug","description","priceCents"],"properties":{"id":{"type":"string","example":"mst_456"},"title":{"type":"string","example":"Máster AI Engineer con Java & LangChain"},"slug":{"type":"string","example":"master-ai-engineer-java-langchain-spring"},"description":{"type":"string","example":"Construye sistemas RAG y agentes autónomos en Java."},"priceCents":{"type":"number","example":49900}}},"UserProfile":{"type":"object","required":["id","firstName","lastName"],"properties":{"id":{"type":"string","example":"usr_789"},"firstName":{"type":"string","example":"Ricardo"},"lastName":{"type":"string","example":"Romero"},"bio":{"type":"string","example":"Java & Spring Boot Architect"},"completedCoursesCount":{"type":"number","example":5}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"NOT_FOUND"},"message":{"type":"string","example":"The requested resource was not found."},"hint":{"type":"string","example":"Check resource ID or URL parameters."}}}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Pass Supabase JWT or MCP Bearer Token in Authorization header."}}}}