{ "openapi": "3.0.3", "info": { "title": "Kubeasy CLI API", "version": "1.0.0", "description": "Public API for the Kubeasy platform consumed by the CLI. Web routes use session cookie authentication; CLI routes use Bearer token authentication." }, "servers": [ { "url": "https://kubeasy.dev", "description": "Production" }, { "url": "http://localhost:3024", "description": "Development" } ], "components": { "securitySchemes": { "SessionAuth": { "type": "apiKey", "in": "cookie", "name": "better-auth.session_token", "description": "Session cookie set after login via better-auth" }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key obtained via `kubeasy login`. Used by the CLI and accepted on all public API routes." } }, "schemas": {}, "parameters": {} }, "paths": { "/api/user/me": { "get": { "operationId": "getUserMe", "summary": "Get current user profile", "tags": [ "CLI" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string", "nullable": true } }, "required": [ "id", "email", "name" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/challenges": { "get": { "operationId": "listChallenges", "summary": "List challenges", "tags": [ "CLI" ], "security": [ { "SessionAuth": [] }, { "BearerAuth": [] }, {} ], "parameters": [ { "schema": { "type": "string", "enum": [ "easy", "medium", "hard" ] }, "required": false, "name": "difficulty", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "type", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "theme", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "showCompleted", "in": "query" } ], "responses": { "200": { "description": "Challenge list", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenges": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "theme": { "type": "string" }, "themeSlug": { "type": "string" }, "difficulty": { "type": "string", "enum": [ "easy", "medium", "hard" ] }, "type": { "type": "string" }, "typeSlug": { "type": "string" }, "estimatedTime": { "type": "integer" }, "initialSituation": { "type": "string" }, "ofTheWeek": { "type": "boolean" }, "completedCount": { "type": "integer" }, "userStatus": { "type": "string", "nullable": true } }, "required": [ "slug", "title", "description", "theme", "themeSlug", "difficulty", "type", "typeSlug", "estimatedTime", "initialSituation", "ofTheWeek", "completedCount", "userStatus" ] } }, "count": { "type": "integer" } }, "required": [ "challenges", "count" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/challenges/{slug}": { "get": { "operationId": "getChallenge", "summary": "Get challenge details", "tags": [ "CLI" ], "security": [], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Challenge details", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge": { "type": "object", "nullable": true, "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "theme": { "type": "string" }, "themeSlug": { "type": "string" }, "difficulty": { "type": "string", "enum": [ "easy", "medium", "hard" ] }, "type": { "type": "string" }, "typeSlug": { "type": "string" }, "estimatedTime": { "type": "integer" }, "initialSituation": { "type": "string" }, "ofTheWeek": { "type": "boolean" }, "available": { "type": "boolean" }, "starterFriendly": { "type": "boolean" } }, "required": [ "slug", "title", "description", "theme", "themeSlug", "difficulty", "type", "typeSlug", "estimatedTime", "initialSituation", "ofTheWeek", "available", "starterFriendly" ] } }, "required": [ "challenge" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/challenges/meta": { "get": { "operationId": "getChallengeMeta", "summary": "Get challenge metadata (themes, types, difficulties)", "tags": [ "CLI" ], "responses": { "200": { "description": "Metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "themes": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "logo": { "type": "string" } }, "required": [ "slug", "name", "description", "logo" ] } }, "types": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "logo": { "type": "string" } }, "required": [ "slug", "name", "description", "logo" ] } }, "difficulties": { "type": "array", "items": { "type": "string" } } }, "required": [ "themes", "types", "difficulties" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/challenges/{slug}/yaml": { "get": { "operationId": "getChallengeYaml", "summary": "Get challenge.yaml", "tags": [ "CLI" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Raw YAML", "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/challenges/{slug}/manifests": { "get": { "operationId": "getChallengeManifests", "summary": "Get challenge manifests tar.gz", "tags": [ "CLI" ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Binary data", "content": { "application/gzip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/progress/{slug}": { "get": { "operationId": "getChallengeStatus", "summary": "Get challenge progress", "tags": [ "CLI" ], "security": [ { "SessionAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Challenge progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "in_progress", "completed" ] }, "startedAt": { "type": "string", "nullable": true, "format": "date-time" }, "completedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "status" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/progress/{slug}/start": { "post": { "operationId": "startChallenge", "summary": "Start a challenge", "tags": [ "CLI" ], "security": [ { "SessionAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Challenge started", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "in_progress", "completed" ] }, "startedAt": { "type": "string", "nullable": true, "format": "date-time" }, "message": { "type": "string" } }, "required": [ "status" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/progress/{slug}/reset": { "post": { "operationId": "resetChallenge", "summary": "Reset challenge progress", "tags": [ "CLI" ], "security": [ { "SessionAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "responses": { "200": { "description": "Progress reset", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/challenges/{slug}/submit": { "post": { "operationId": "submitChallenge", "summary": "Submit challenge validation results", "tags": [ "CLI" ], "security": [ { "SessionAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "slug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "objectiveKey": { "type": "string" }, "passed": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "objectiveKey", "passed" ] }, "minItems": 1 }, "auditEvents": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "verb": { "type": "string", "maxLength": 64 }, "resource": { "type": "string", "maxLength": 128 }, "subresource": { "type": "string", "maxLength": 128 }, "name": { "type": "string", "maxLength": 253 }, "namespace": { "type": "string", "maxLength": 63 }, "userAgent": { "type": "string", "maxLength": 512 }, "responseCode": { "type": "integer", "minimum": 100, "maximum": 599 } }, "required": [ "timestamp", "verb", "resource" ] }, "maxItems": 10000 } }, "required": [ "results" ] } } } }, "responses": { "200": { "description": "All objectives passed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "objectives": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "passed": { "type": "boolean" }, "category": { "type": "string", "enum": [ "status", "condition", "log", "event", "connectivity", "rbac", "spec", "triggered" ] }, "message": { "type": "string" } }, "required": [ "key", "title", "passed", "category" ] } } }, "required": [ "success", "objectives" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "409": { "description": "Challenge already completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "422": { "description": "Some objectives failed or missing/unknown objectives", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "objectives": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "passed": { "type": "boolean" }, "category": { "type": "string", "enum": [ "status", "condition", "log", "event", "connectivity", "rbac", "spec", "triggered" ] }, "message": { "type": "string" } }, "required": [ "key", "title", "passed", "category" ] } }, "failedObjectives": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "message": { "type": "string" } }, "required": [ "key", "title", "message" ] } } }, "required": [ "success", "objectives", "failedObjectives" ] }, { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/cli/track/login": { "post": { "operationId": "trackCliLogin", "summary": "Track CLI login and metadata", "tags": [ "CLI" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cliVersion": { "type": "string" }, "os": { "type": "string" }, "arch": { "type": "string" } }, "required": [ "cliVersion", "os", "arch" ] } } } }, "responses": { "200": { "description": "Login tracked", "content": { "application/json": { "schema": { "type": "object", "properties": { "firstLogin": { "type": "boolean" } }, "required": [ "firstLogin" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } } } } }, "/api/cli/track/setup": { "post": { "operationId": "trackSetup", "summary": "Track CLI cluster initialisation", "tags": [ "CLI" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cliVersion": { "type": "string" }, "os": { "type": "string" }, "arch": { "type": "string" } }, "required": [ "cliVersion", "os", "arch" ] } } } }, "responses": { "200": { "description": "Setup tracked", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "firstTime": { "type": "boolean" } }, "required": [ "success", "firstTime" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "details": { "type": "string" } }, "required": [ "error" ] } } } } } } } } }