sealos-cli 0.1.0

package/src/docs/template_openapi.json

@@ -0,0 +1 @@
+{"openapi":"3.1.0","info":{"title":"Template API","version":"2.0.0-alpha","description":"This API provides endpoints for managing application templates and instances in the Sealos platform.\n\n## Authentication\n\nBrowsing templates is public. Deploying instances requires a URL-encoded kubeconfig in the `Authorization` header. Encode with `encodeURIComponent(kubeconfigYaml)` before setting the header value. Obtain your kubeconfig from the Sealos console.\n\n## Errors\n\nAll error responses use a unified format:\n\n```json\n{\n  \"error\": {\n    \"type\": \"validation_error\",\n    \"code\": \"INVALID_PARAMETER\",\n    \"message\": \"...\",\n    \"details\": [...]\n  }\n}\n```\n\n- `type` — high-level category (e.g. `validation_error`, `resource_error`, `internal_error`)\n- `code` — stable identifier for programmatic handling\n- `message` — human-readable explanation\n- `details` — optional extra context; shape varies by `code` (field list, string, or object)\n\n## Operations\n\n**Query** (read-only): returns `200 OK` with data in the response body.\n\n**Mutation** (write):\n- Create → `201 Created` with the created resource in the response body.\n- Update / Delete → `204 No Content` with no response body."},"servers":[{"url":"http://localhost:3000/api/v2alpha","description":"Local development"},{"url":"{baseUrl}/api/v2alpha","description":"Custom","variables":{"baseUrl":{"default":"https://template.example.com","description":"Base URL of your instance (e.g. https://template.192.168.x.x.nip.io)"}}}],"security":[{"kubeconfigAuth":[]}],"tags":[{"name":"Query","description":"Read-only operations. Success: `200 OK` with data in the response body."},{"name":"Mutation","description":"Write operations. Create: `201 Created` with the new resource. Update/Delete: `204 No Content`."}],"paths":{"/templates":{"get":{"tags":["Query"],"summary":"List all templates","description":"Returns metadata only (no resource calculation). Response headers: `Cache-Control` (public, max-age=300, s-maxage=600), `ETag`. When categories exist, top category keys are returned in `X-Menu-Keys` (comma-separated). For full details including resource requirements, use `/templates/{name}`.","operationId":"listTemplates","security":[],"parameters":[{"in":"query","name":"language","schema":{"description":"Language code for internationalization (e.g., \"en\", \"zh\"). Defaults to \"en\"","example":"en","type":"string"},"description":"Language code for internationalization (e.g., \"en\", \"zh\"). Defaults to \"en\""}],"responses":{"200":{"description":"Successfully retrieved template list","headers":{"Cache-Control":{"description":"Caching directive: public, max-age=300, s-maxage=600","schema":{"type":"string","example":"public, max-age=300, s-maxage=600"}},"ETag":{"description":"Entity tag for caching, format: \"template-list-{language}\"","schema":{"type":"string","example":"\"template-list-en\""}},"X-Menu-Keys":{"description":"Top category keys (comma-separated). Present only when categories exist.","schema":{"type":"string","example":"ai,database"}}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Unique template identifier"},"resourceType":{"type":"string","const":"template","description":"Resource type, always \"template\""},"readme":{"type":"string","description":"URL to README documentation. Empty string when not available."},"icon":{"type":"string","description":"URL to template icon image. Empty string when not available."},"description":{"type":"string","description":"Brief description of the template"},"gitRepo":{"type":"string","description":"Git repository URL. Empty string when not available."},"category":{"type":"array","items":{"type":"string"},"description":"Template categories (e.g., [\"ai\", \"database\"])"},"args":{"type":"object","properties":{},"additionalProperties":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable explanation of the argument"},"type":{"type":"string","description":"Argument type (e.g. \"string\", \"number\", \"boolean\", \"password\")"},"default":{"type":"string","description":"Default value used during deployment"},"required":{"type":"boolean","description":"Whether this argument is mandatory"}},"required":["description","type","default","required"],"additionalProperties":false,"description":"Template argument configuration"},"description":"Arguments required for template deployment"},"deployCount":{"type":"number","description":"Number of deployments (includes multiplier for display)"}},"required":["name","resourceType","readme","icon","description","gitRepo","category","args","deployCount"],"additionalProperties":false},"description":"Array of template items (returned directly without wrapper object)"},"examples":{"templateList":{"summary":"Sample template list","value":[{"name":"perplexica","resourceType":"template","readme":"https://raw.githubusercontent.com/ItzCrazyKns/Perplexica/master/README.md","icon":"https://raw.githubusercontent.com/ItzCrazyKns/Perplexica/refs/heads/master/src/app/favicon.ico","description":"AI-powered search engine","gitRepo":"https://github.com/ItzCrazyKns/Perplexica","category":["ai"],"args":{"OPENAI_API_KEY":{"description":"OpenAI API Key","type":"string","default":"","required":true}},"deployCount":156}]}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["internal_error"],"description":"High-level error type for categorization"},"code":{"type":"string","enum":["INTERNAL_ERROR"],"description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Raw error string from the underlying system, for troubleshooting.","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"internalError":{"summary":"Failed to load templates","value":{"error":{"type":"internal_error","code":"INTERNAL_ERROR","message":"Failed to load templates.","details":"File read error"}}}}}}}}}},"/templates/{name}":{"get":{"tags":["Query"],"summary":"Get template details","description":"Returns complete template metadata with dynamically calculated resource requirements (CPU, memory, storage, NodePort count) derived from the template YAML. Falls back to static configuration if calculation fails. Response headers: `Cache-Control` (public, max-age=300, s-maxage=600), `ETag`.","operationId":"getTemplate","security":[],"parameters":[{"in":"path","name":"name","schema":{"type":"string","description":"Template name identifier (e.g., \"perplexica\", \"yourls\")","example":"perplexica"},"required":true,"description":"Template name identifier (e.g., \"perplexica\", \"yourls\")"},{"in":"query","name":"language","schema":{"description":"Language code for internationalization (e.g., \"en\", \"zh\"). Defaults to \"en\"","example":"en","type":"string"},"description":"Language code for internationalization (e.g., \"en\", \"zh\"). Defaults to \"en\""}],"responses":{"200":{"description":"Successfully retrieved template details","headers":{"Cache-Control":{"description":"Caching directive: public, max-age=300, s-maxage=600","schema":{"type":"string","example":"public, max-age=300, s-maxage=600"}},"ETag":{"description":"Entity tag for caching, format: \"{name}-{language}\"","schema":{"type":"string","example":"\"perplexica-en\""}}},"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Unique template identifier"},"resourceType":{"type":"string","const":"template","description":"Resource type, always \"template\""},"readme":{"type":"string","description":"URL to README documentation. Empty string when not available."},"icon":{"type":"string","description":"URL to template icon image. Empty string when not available."},"description":{"type":"string","description":"Brief description of the template"},"gitRepo":{"type":"string","description":"Git repository URL. Empty string when not available."},"category":{"type":"array","items":{"type":"string"},"description":"Template categories (e.g., [\"ai\", \"database\"])"},"args":{"type":"object","properties":{},"additionalProperties":{"type":"object","properties":{"description":{"type":"string","description":"Human-readable explanation of the argument"},"type":{"type":"string","description":"Argument type (e.g. \"string\", \"number\", \"boolean\", \"password\")"},"default":{"type":"string","description":"Default value used during deployment"},"required":{"type":"boolean","description":"Whether this argument is mandatory"}},"required":["description","type","default","required"],"additionalProperties":false,"description":"Template argument configuration"},"description":"Arguments required for template deployment"},"deployCount":{"type":"number","description":"Number of deployments (includes multiplier for display)"},"quota":{"type":"object","properties":{"cpu":{"type":"number","description":"Required CPU cores in vCPU"},"memory":{"type":"number","description":"Required memory in GiB"},"storage":{"type":"number","description":"Required storage in GiB"},"nodeport":{"type":"number","description":"Number of NodePort services required"}},"required":["cpu","memory","storage","nodeport"],"additionalProperties":false,"description":"Calculated resource requirements"}},"required":["name","resourceType","readme","icon","description","gitRepo","category","args","deployCount","quota"],"additionalProperties":false},"examples":{"templateDetail":{"summary":"Sample template with resource calculation","value":{"name":"perplexica","resourceType":"template","quota":{"cpu":1,"memory":2.25,"storage":2,"nodeport":0},"readme":"https://raw.githubusercontent.com/ItzCrazyKns/Perplexica/master/README.md","icon":"https://raw.githubusercontent.com/ItzCrazyKns/Perplexica/refs/heads/master/src/app/favicon.ico","description":"AI-powered search engine","gitRepo":"https://github.com/ItzCrazyKns/Perplexica","category":["ai"],"args":{"OPENAI_API_KEY":{"description":"The API Key of the OpenAI-compatible service","type":"string","default":"","required":true}},"deployCount":156}}}}}},"400":{"description":"Bad request - template name is required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["validation_error"],"description":"High-level error type for categorization"},"code":{"type":"string","enum":["INVALID_PARAMETER"],"description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"For INVALID_PARAMETER: Array<{ field, message }>. For INVALID_VALUE: optional string. Omitted for other codes.","anyOf":[{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Field path using dot/bracket notation, e.g. \"ports[0].number\""},"message":{"type":"string","description":"Validation error message for this field"}},"required":["field","message"],"additionalProperties":false}},{"type":"string"}]}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"nameRequired":{"summary":"Template name is required","value":{"error":{"type":"validation_error","code":"INVALID_PARAMETER","message":"Template name is required.","details":[{"field":"name","message":"Required"}]}}}}}}},"404":{"description":"Template not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","const":"resource_error","description":"High-level error type for categorization"},"code":{"type":"string","const":"NOT_FOUND","description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Typically omitted. May contain additional context in edge cases.","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"templateNotFound":{"summary":"Template not found","value":{"error":{"type":"resource_error","code":"NOT_FOUND","message":"Template 'nonexistent' not found."}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["internal_error"],"description":"High-level error type for categorization"},"code":{"type":"string","enum":["INTERNAL_ERROR"],"description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Raw error string from the underlying system, for troubleshooting.","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"internalError":{"summary":"Failed to get template details","value":{"error":{"type":"internal_error","code":"INTERNAL_ERROR","message":"Failed to get template details.","details":"YAML parsing error"}}}}}}}}}},"/templates/raw":{"post":{"tags":["Mutation"],"summary":"Deploy template from raw YAML","description":"Deploy an arbitrary or custom template by supplying its raw YAML directly in the request body. The instance name is auto-generated from `${{ random(8) }}` inside `spec.defaults.app_name`. Use `dryRun: true` to validate the resources against the Kubernetes API without creating anything.\n\n**Example — dry-run a custom template:**\n```json\n{\n  \"yaml\": \"apiVersion: app.sealos.io/v1\\nkind: Template\\n...\",\n  \"dryRun\": true\n}\n```","operationId":"deployRawTemplate","requestBody":{"required":true,"description":"Template deployment configuration","content":{"application/json":{"schema":{"type":"object","properties":{"yaml":{"type":"string","description":"Full template YAML string. Must start with a `kind: Template` document, followed by one or more `---`-separated Kubernetes resource documents.","example":"apiVersion: app.sealos.io/v1\nkind: Template\nmetadata:\n  name: my-app\nspec:\n  defaults:\n    app_name:\n      type: string\n      value: my-app-${{ random(8) }}\n---\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: ${{ defaults.app_name }}\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: ${{ defaults.app_name }}\n  template:\n    metadata:\n      labels:\n        app: ${{ defaults.app_name }}\n    spec:\n      containers:\n        - name: app\n          image: nginx:latest\n          resources:\n            limits:\n              cpu: 100m\n              memory: 256Mi"},"args":{"type":"object","properties":{},"additionalProperties":{"type":"string","description":"Template variable value"},"description":"Template variable key-value pairs that override or supply `spec.inputs` fields. Only args without a non-empty default are required.","example":{"MY_SECRET":"my-secret-value"}},"dryRun":{"type":"boolean","description":"If true, validates the resources against the Kubernetes API but does not create anything. Returns 200 with a preview. Default: false.","example":true}},"required":["yaml"]}}}},"responses":{"200":{"description":"Dry-run preview — resources validated but not created","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Auto-generated instance name from ${{ random(8) }} in spec.defaults"},"resourceType":{"type":"string","const":"instance","description":"Always \"instance\""},"dryRun":{"type":"boolean","const":true,"description":"Always true for dry-run responses"},"args":{"type":"object","properties":{},"additionalProperties":{"type":"string"},"description":"Resolved template arguments after merging user-provided values with defaults"},"resources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Resource name"},"uid":{"type":"string","description":"Kubernetes UID"},"resourceType":{"type":"string","description":"Resource type (lowercase k8s kind)"},"quota":{"type":"object","properties":{"cpu":{"description":"CPU cores","type":"number"},"memory":{"description":"Memory in GiB","type":"number"},"storage":{"description":"Storage in GiB","type":"number"},"replicas":{"description":"Number of replicas","type":"number"}},"additionalProperties":false,"description":"Resource quota (for Deployment/StatefulSet/Cluster)"}},"required":["name","uid","resourceType"],"additionalProperties":false},"description":"Preview of sub-resources that would be created (Instance resource excluded)"}},"required":["name","resourceType","dryRun","args"],"additionalProperties":false},"examples":{"dryRunPreview":{"summary":"Dry-run result","value":{"name":"myapp-abcdefgh","resourceType":"instance","dryRun":true,"args":{},"resources":[{"name":"myapp-abcdefgh","uid":"","resourceType":"deployment","quota":{"cpu":0.1,"memory":0.25,"storage":0,"replicas":1}}]}}}}}},"201":{"description":"Template deployed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Instance name (matches the name specified in the request)"},"uid":{"type":"string","description":"Kubernetes UID of the Instance resource"},"resourceType":{"type":"string","const":"instance","description":"Always \"instance\""},"displayName":{"type":"string","description":"Display name"},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp"},"args":{"type":"object","properties":{},"additionalProperties":{"type":"string","description":"Template variable value"},"description":"Resolved template arguments after merging user-provided values with defaults"},"resources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Resource name"},"uid":{"type":"string","description":"Kubernetes UID"},"resourceType":{"type":"string","description":"Resource type (lowercase k8s kind)"},"quota":{"type":"object","properties":{"cpu":{"description":"CPU cores","type":"number"},"memory":{"description":"Memory in GiB","type":"number"},"storage":{"description":"Storage in GiB","type":"number"},"replicas":{"description":"Number of replicas","type":"number"}},"additionalProperties":false,"description":"Resource quota (for Deployment/StatefulSet/Cluster)"}},"required":["name","uid","resourceType"],"additionalProperties":false},"description":"Sub-resources created for this instance"}},"required":["name","uid","resourceType","displayName","createdAt","args"],"additionalProperties":false},"examples":{"deployed":{"summary":"Template deployed successfully","value":{"name":"myapp-abcdefgh","uid":"778bf3c6-b412-4a02-908b-cf1470867c93","resourceType":"instance","displayName":"","createdAt":"2026-01-28T03:31:01Z","args":{},"resources":[{"name":"myapp-abcdefgh","uid":"5bd2c77d-b8f4-4aa4-97ee-c205f2d10aa9","resourceType":"deployment","quota":{"cpu":0.1,"memory":0.25,"storage":0,"replicas":1}}]}}}}}},"400":{"description":"Bad request — missing or invalid YAML / missing required args","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["validation_error"],"description":"High-level error type for categorization"},"code":{"type":"string","enum":["INVALID_PARAMETER","INVALID_VALUE"],"description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"For INVALID_PARAMETER: Array<{ field, message }>. For INVALID_VALUE: optional string. Omitted for other codes.","anyOf":[{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Field path using dot/bracket notation, e.g. \"ports[0].number\""},"message":{"type":"string","description":"Validation error message for this field"}},"required":["field","message"],"additionalProperties":false}},{"type":"string"}]}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"missingYaml":{"summary":"YAML is required","value":{"error":{"type":"validation_error","code":"INVALID_PARAMETER","message":"Template YAML is required.","details":[{"field":"yaml","message":"Required"}]}}},"invalidYaml":{"summary":"First document is not kind: Template","value":{"error":{"type":"validation_error","code":"INVALID_VALUE","message":"The first YAML type is not Template"}}},"missingArgs":{"summary":"Required template args missing","value":{"error":{"type":"validation_error","code":"INVALID_VALUE","message":"Missing required parameters: MY_SECRET."}}}}}}},"401":{"description":"Unauthorized — missing or invalid kubeconfig","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","const":"authentication_error","description":"High-level error type for categorization"},"code":{"type":"string","const":"AUTHENTICATION_REQUIRED","description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Typically omitted. May contain additional context in edge cases.","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"missingAuth":{"summary":"Missing authentication","value":{"error":{"type":"authentication_error","code":"AUTHENTICATION_REQUIRED","message":"Invalid or missing kubeconfig."}}}}}}},"403":{"description":"Forbidden — insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","const":"authorization_error","description":"High-level error type for categorization"},"code":{"type":"string","enum":["PERMISSION_DENIED"],"description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Typically omitted. May contain additional context in edge cases.","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"forbidden":{"summary":"Insufficient privileges","value":{"error":{"type":"authorization_error","code":"PERMISSION_DENIED","message":"Permission denied: insufficient privileges to create resources.","details":"deployments.apps is forbidden: User \"system:serviceaccount:ns-xxx\" cannot create resource \"deployments\""}}}}}}},"409":{"description":"Conflict — instance already exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","const":"resource_error","description":"High-level error type for categorization"},"code":{"type":"string","enum":["ALREADY_EXISTS"],"description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Typically omitted. May contain additional context in edge cases.","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"alreadyExists":{"summary":"Instance already exists","value":{"error":{"type":"resource_error","code":"ALREADY_EXISTS","message":"Instance 'myapp-abcdefgh' already exists.","details":"deployments.apps \"myapp-abcdefgh\" already exists"}}}}}}},"422":{"description":"Unprocessable Entity — K8s rejected the resource spec","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","const":"operation_error","description":"High-level error type for categorization"},"code":{"type":"string","const":"INVALID_RESOURCE_SPEC","description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Raw K8s rejection reason (admission webhook message, invalid field error, quota exceeded message).","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"invalidSpec":{"summary":"Resource spec rejected by cluster","value":{"error":{"type":"operation_error","code":"INVALID_RESOURCE_SPEC","message":"Template validation failed: invalid resource specification.","details":"admission webhook \"vingress.sealos.io\" denied the request: cannot verify ingress host"}}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["operation_error","internal_error"],"description":"High-level error type for categorization"},"code":{"type":"string","enum":["KUBERNETES_ERROR","INTERNAL_ERROR"],"description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Raw error string from the underlying system, for troubleshooting.","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"internalError":{"summary":"Unexpected server error","value":{"error":{"type":"internal_error","code":"INTERNAL_ERROR","message":"Failed to deploy template.","details":"Template parsing error"}}}}}}},"503":{"description":"Service Unavailable — Kubernetes cluster temporarily unreachable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","const":"internal_error","description":"High-level error type for categorization"},"code":{"type":"string","const":"SERVICE_UNAVAILABLE","description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Raw connection error from the underlying system (e.g. ECONNREFUSED).","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"clusterUnavailable":{"summary":"Cluster unreachable","value":{"error":{"type":"internal_error","code":"SERVICE_UNAVAILABLE","message":"Kubernetes cluster is temporarily unavailable.","details":"connect ECONNREFUSED 10.0.0.1:6443"}}}}}}}}}},"/templates/instances":{"post":{"tags":["Mutation"],"summary":"Create template instance","description":"Deploy a named instance of a template into the user's Kubernetes namespace. User-provided `args` are merged with the template's declared defaults — only args with no default value are required. The `args` field in the response reflects the fully resolved values after applying defaults.\n\n**Example — create a Perplexica instance:**\n```json\n{\n  \"name\": \"my-app-instance\",\n  \"template\": \"perplexica\",\n  \"args\": {\n    \"OPENAI_API_KEY\": \"<your-api-key>\",\n    \"OPENAI_MODEL_NAME\": \"gpt-4o\"\n  }\n}\n```","operationId":"createInstance","requestBody":{"required":true,"description":"Instance creation configuration","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Instance name. 1–63 lowercase alphanumeric characters or hyphens, must start and end with alphanumeric (Kubernetes DNS subdomain rules). e.g. \"my-perplexica-instance\"","example":"my-perplexica-instance"},"template":{"type":"string","description":"Template name from the catalog. Use GET /templates to list available templates. e.g. \"perplexica\"","example":"perplexica"},"args":{"type":"object","properties":{},"additionalProperties":{"type":"string","description":"Template variable value"},"description":"Template variable key-value pairs. Only args without a default value are required. Use GET /templates/{name} to see which args are required and their defaults.","example":{"OPENAI_API_KEY":"sk-xxxxxxxxxxxxxxxxxxxx","OPENAI_MODEL_NAME":"gpt-4o"}}},"required":["name","template"]}}}},"responses":{"201":{"description":"Instance created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Instance name (matches the name specified in the request)"},"uid":{"type":"string","description":"Kubernetes UID of the Instance resource"},"resourceType":{"type":"string","const":"instance","description":"Always \"instance\""},"displayName":{"type":"string","description":"Display name"},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp"},"args":{"type":"object","properties":{},"additionalProperties":{"type":"string","description":"Template variable value"},"description":"Resolved template arguments after merging user-provided values with defaults"},"resources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Resource name"},"uid":{"type":"string","description":"Kubernetes UID"},"resourceType":{"type":"string","description":"Resource type (lowercase k8s kind)"},"quota":{"type":"object","properties":{"cpu":{"description":"CPU cores","type":"number"},"memory":{"description":"Memory in GiB","type":"number"},"storage":{"description":"Storage in GiB","type":"number"},"replicas":{"description":"Number of replicas","type":"number"}},"additionalProperties":false,"description":"Resource quota (for Deployment/StatefulSet/Cluster)"}},"required":["name","uid","resourceType"],"additionalProperties":false},"description":"Sub-resources created for this instance"}},"required":["name","uid","resourceType","displayName","createdAt","args"],"additionalProperties":false},"examples":{"instanceCreated":{"summary":"Instance created successfully","value":{"name":"my-perplexica-instance","uid":"778bf3c6-b412-4a02-908b-cf1470867c93","resourceType":"instance","displayName":"","createdAt":"2026-01-28T03:31:01Z","args":{"OPENAI_API_KEY":"sk-xxxxxxxxxxxxxxxxxxxxxxxx","OPENAI_API_URL":"https://api.openai.com/v1","OPENAI_MODEL_NAME":"gpt-4o"},"resources":[{"name":"my-perplexica-instance-searxng","uid":"5bd2c77d-b8f4-4aa4-97ee-c205f2d10aa9","resourceType":"deployment","quota":{"cpu":0.1,"memory":0.25,"storage":0,"replicas":1}},{"name":"my-perplexica-instance","uid":"256e2577-fa3a-4471-a94c-8cbd5410187c","resourceType":"statefulset","quota":{"cpu":0.2,"memory":0.5,"storage":1,"replicas":1}}]}}}}}},"400":{"description":"Bad request - missing or invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["validation_error"],"description":"High-level error type for categorization"},"code":{"type":"string","enum":["INVALID_PARAMETER","INVALID_VALUE"],"description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"For INVALID_PARAMETER: Array<{ field, message }>. For INVALID_VALUE: optional string. Omitted for other codes.","anyOf":[{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"Field path using dot/bracket notation, e.g. \"ports[0].number\""},"message":{"type":"string","description":"Validation error message for this field"}},"required":["field","message"],"additionalProperties":false}},{"type":"string"}]}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"invalidParameter":{"summary":"Instance or template name required","value":{"error":{"type":"validation_error","code":"INVALID_PARAMETER","message":"Instance name is required.","details":[{"field":"name","message":"Required"}]}}},"invalidValue":{"summary":"Invalid instance name format","value":{"error":{"type":"validation_error","code":"INVALID_VALUE","message":"Instance name must start and end with a lowercase letter or number, and can only contain lowercase letters, numbers, and hyphens."}}}}}}},"401":{"description":"Unauthorized - Missing or invalid kubeconfig","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","const":"authentication_error","description":"High-level error type for categorization"},"code":{"type":"string","const":"AUTHENTICATION_REQUIRED","description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Typically omitted. May contain additional context in edge cases.","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"missingAuth":{"summary":"Missing authentication","value":{"error":{"type":"authentication_error","code":"AUTHENTICATION_REQUIRED","message":"Invalid or missing kubeconfig."}}}}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","const":"authorization_error","description":"High-level error type for categorization"},"code":{"type":"string","enum":["PERMISSION_DENIED"],"description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Typically omitted. May contain additional context in edge cases.","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"insufficientPermissions":{"summary":"Insufficient privileges to create resources","value":{"error":{"type":"authorization_error","code":"PERMISSION_DENIED","message":"Permission denied: insufficient privileges to create resources.","details":"deployments.apps is forbidden: User \"system:serviceaccount:ns-xxx\" cannot create resource \"deployments\" in API group \"apps\" in the namespace \"ns-xxx\""}}}}}}},"404":{"description":"Not Found - Template not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","const":"resource_error","description":"High-level error type for categorization"},"code":{"type":"string","const":"NOT_FOUND","description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Typically omitted. May contain additional context in edge cases.","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"templateNotFound":{"summary":"Template does not exist","value":{"error":{"type":"resource_error","code":"NOT_FOUND","message":"Template 'nonexistent-template' not found."}}}}}}},"409":{"description":"Conflict - Instance already exists","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","const":"resource_error","description":"High-level error type for categorization"},"code":{"type":"string","enum":["ALREADY_EXISTS"],"description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Typically omitted. May contain additional context in edge cases.","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"alreadyExists":{"summary":"Instance with this name already exists","value":{"error":{"type":"resource_error","code":"ALREADY_EXISTS","message":"Instance 'my-perplexica-instance' already exists.","details":"deployments.apps \"my-perplexica-instance\" already exists"}}}}}}},"422":{"description":"Unprocessable Entity - K8s rejected the resource (admission webhook, invalid field, quota exceeded)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","const":"operation_error","description":"High-level error type for categorization"},"code":{"type":"string","const":"INVALID_RESOURCE_SPEC","description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Raw K8s rejection reason (admission webhook message, invalid field error, quota exceeded message).","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"invalidResourceSpec":{"summary":"Resource spec rejected by cluster","value":{"error":{"type":"operation_error","code":"INVALID_RESOURCE_SPEC","message":"Failed to create instance: invalid resource specification.","details":"admission webhook \"vingress.sealos.io\" denied the request: cannot verify ingress host"}}}}}}},"500":{"description":"Internal Server Error - Kubernetes API error or unexpected failure","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["operation_error","internal_error"],"description":"High-level error type for categorization"},"code":{"type":"string","enum":["KUBERNETES_ERROR","OPERATION_FAILED","INTERNAL_ERROR"],"description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Raw error string from the underlying system, for troubleshooting.","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"kubernetesError":{"summary":"Kubernetes API error","value":{"error":{"type":"operation_error","code":"KUBERNETES_ERROR","message":"Failed to create instance in Kubernetes.","details":"Unexpected error from Kubernetes API"}}},"internalError":{"summary":"Unexpected server error","value":{"error":{"type":"internal_error","code":"INTERNAL_ERROR","message":"Failed to create instance.","details":"Template parsing error"}}}}}}},"503":{"description":"Service Unavailable - Kubernetes cluster temporarily unreachable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","const":"internal_error","description":"High-level error type for categorization"},"code":{"type":"string","const":"SERVICE_UNAVAILABLE","description":"Specific error code for programmatic handling and i18n"},"message":{"type":"string","description":"Human-readable error message"},"details":{"description":"Raw connection error from the underlying system (e.g. ECONNREFUSED).","type":"string"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"examples":{"clusterUnavailable":{"summary":"Cluster unreachable","value":{"error":{"type":"internal_error","code":"SERVICE_UNAVAILABLE","message":"Kubernetes cluster is temporarily unavailable.","details":"connect ECONNREFUSED 10.0.0.1:6443"}}}}}}}}}}},"components":{"securitySchemes":{"kubeconfigAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"URL-encoded kubeconfig YAML. Encode with `encodeURIComponent(kubeconfigYaml)` before setting the header value. Obtain your kubeconfig from the Sealos console."}}}}