{ "openapi": "3.1.0", "info": { "title": "Orchestrator Control Plane API", "description": "", "license": { "name": "" }, "version": "0.1.0" }, "paths": { "/api/v1/commit_tags": { "get": { "tags": [ "commit_tags" ], "operationId": "list_tags", "responses": { "200": { "description": "List of tags", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTagsResponse" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "commit_tags" ], "operationId": "create_tag", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagRequest" } } }, "required": true }, "responses": { "201": { "description": "Tag created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Commit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Tag already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/commit_tags/{tag_name}": { "get": { "tags": [ "commit_tags" ], "operationId": "get_tag", "parameters": [ { "name": "tag_name", "in": "path", "description": "Tag name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tag details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagInfo" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "commit_tags" ], "operationId": "delete_tag", "parameters": [ { "name": "tag_name", "in": "path", "description": "Tag name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Tag deleted" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "commit_tags" ], "operationId": "update_tag", "parameters": [ { "name": "tag_name", "in": "path", "description": "Tag name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTagRequest" } } }, "required": true }, "responses": { "204": { "description": "Tag updated" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Tag or commit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/commits": { "get": { "tags": [ "commits" ], "operationId": "list_commits", "parameters": [ { "name": "limit", "in": "path", "description": "Maximum number of commits to return (default: 50, max: 100)", "required": true, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "path", "description": "Number of commits to skip (default: 0)", "required": true, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of commits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCommitsResponse" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/commits/public": { "get": { "tags": [ "commits" ], "operationId": "list_public_commits", "parameters": [ { "name": "limit", "in": "path", "description": "Maximum number of commits to return (default: 50, max: 100)", "required": true, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "path", "description": "Number of commits to skip (default: 0)", "required": true, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of public commits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCommitsResponse" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/commits/{commit_id}": { "delete": { "tags": [ "commits" ], "operationId": "delete_commit", "parameters": [ { "name": "commit_id", "in": "path", "description": "Commit ID to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Commit deleted" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Commit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Commit in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "commits" ], "operationId": "update_commit", "parameters": [ { "name": "commit_id", "in": "path", "description": "The commit ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommitRequest" } } }, "required": true }, "responses": { "200": { "description": "Commit updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitInfo" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Commit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/deploy": { "post": { "tags": [ "deploy" ], "summary": "Deploy a GitHub repository to a new Vers project.", "operationId": "deploy_handler", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployRequest" } } }, "required": true }, "responses": { "202": { "description": "Deploy initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeployResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Repository not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Project name conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "501": { "description": "GitHub App not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/domains": { "get": { "tags": [ "domains" ], "operationId": "list_domains", "parameters": [ { "name": "vm_id", "in": "query", "description": "Filter by VM ID", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of domains", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DomainResponse" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "domains" ], "operationId": "create_domain", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomainRequest" } } }, "required": true }, "responses": { "201": { "description": "Domain created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Domain already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/domains/{domain_id}": { "get": { "tags": [ "domains" ], "operationId": "get_domain", "parameters": [ { "name": "domain_id", "in": "path", "description": "Domain ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Domain details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "domains" ], "operationId": "delete_domain", "parameters": [ { "name": "domain_id", "in": "path", "description": "Domain ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Domain deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDomainResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/env_vars": { "get": { "tags": [ "env_vars" ], "operationId": "list_env_vars", "responses": { "200": { "description": "Current environment variables", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvVarsResponse" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "env_vars" ], "operationId": "set_env_vars", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetEnvVarsRequest" } } }, "required": true }, "responses": { "200": { "description": "Environment variables updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvVarsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/env_vars/{key}": { "delete": { "tags": [ "env_vars" ], "operationId": "delete_env_var", "parameters": [ { "name": "key", "in": "path", "description": "Environment variable key to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Environment variable deleted" }, "401": { "description": "Unauthorized" }, "404": { "description": "Environment variable not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/images": { "get": { "tags": [ "images" ], "operationId": "list_images", "parameters": [ { "name": "limit", "in": "path", "description": "Maximum number of images to return (default: 50, max: 100)", "required": true, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "path", "description": "Number of images to skip (default: 0)", "required": true, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of base images", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBaseImagesResponse" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/images/create": { "post": { "tags": [ "images" ], "operationId": "create_image", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBaseImageRequest" } } }, "required": true }, "responses": { "201": { "description": "Image creation job started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBaseImageResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "409": { "description": "Image name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/images/images/{base_image_id}": { "delete": { "tags": [ "images" ], "operationId": "delete_image", "parameters": [ { "name": "base_image_id", "in": "path", "description": "Base image ID (UUID)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Image deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteBaseImageResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - not owner of image", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Image not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Image is in use by VMs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/images/upload": { "post": { "tags": [ "images" ], "operationId": "upload_image", "parameters": [ { "name": "image_name", "in": "path", "description": "The name for the new base image", "required": true, "schema": { "type": "string" } }, { "name": "size_mib", "in": "path", "description": "Size of the image in MiB (default: 512, min: 512, max: 32768)", "required": true, "schema": { "type": [ "integer", "null" ], "format": "int32" } } ], "responses": { "201": { "description": "Image upload started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadBaseImageResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "409": { "description": "Image name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Upload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/images/{image_name}/status": { "get": { "tags": [ "images" ], "operationId": "get_image_status", "parameters": [ { "name": "image_name", "in": "path", "description": "Image name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Image status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseImageStatusResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Image not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/keys/validate": { "post": { "tags": [ "keys" ], "operationId": "validate_key", "responses": { "200": { "description": "API key is valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateKeyResponse" } } } }, "401": { "description": "API key is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/public/repositories": { "get": { "tags": [ "public_repositories" ], "operationId": "list_public_repositories", "responses": { "200": { "description": "List of public repositories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPublicRepositoriesResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/public/repositories/{org_name}/{repo_name}": { "get": { "tags": [ "public_repositories" ], "operationId": "get_public_repository", "parameters": [ { "name": "org_name", "in": "path", "description": "Organization name", "required": true, "schema": { "type": "string" } }, { "name": "repo_name", "in": "path", "description": "Repository name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public repository details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRepositoryInfo" } } } }, "404": { "description": "Repository not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/public/repositories/{org_name}/{repo_name}/tags": { "get": { "tags": [ "public_repositories" ], "operationId": "list_public_repo_tags", "parameters": [ { "name": "org_name", "in": "path", "description": "Organization name", "required": true, "schema": { "type": "string" } }, { "name": "repo_name", "in": "path", "description": "Repository name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of tags in public repository", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRepoTagsResponse" } } } }, "404": { "description": "Repository not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/public/repositories/{org_name}/{repo_name}/tags/{tag_name}": { "get": { "tags": [ "public_repositories" ], "operationId": "get_public_repo_tag", "parameters": [ { "name": "org_name", "in": "path", "description": "Organization name", "required": true, "schema": { "type": "string" } }, { "name": "repo_name", "in": "path", "description": "Repository name", "required": true, "schema": { "type": "string" } }, { "name": "tag_name", "in": "path", "description": "Tag name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tag details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoTagInfo" } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/repositories": { "get": { "tags": [ "repositories" ], "operationId": "list_repositories", "responses": { "200": { "description": "List of repositories", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRepositoriesResponse" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "repositories" ], "operationId": "create_repository", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRepositoryRequest" } } }, "required": true }, "responses": { "201": { "description": "Repository created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRepositoryResponse" } } } }, "400": { "description": "Invalid name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "409": { "description": "Repository already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/repositories/fork": { "post": { "tags": [ "repositories" ], "operationId": "fork_repository", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkRepositoryRequest" } } }, "required": true }, "responses": { "201": { "description": "Repository forked successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkRepositoryResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Source repository or tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Target repository already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/repositories/{repo_name}": { "get": { "tags": [ "repositories" ], "operationId": "get_repository", "parameters": [ { "name": "repo_name", "in": "path", "description": "Repository name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Repository details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryInfo" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Repository not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "repositories" ], "operationId": "delete_repository", "parameters": [ { "name": "repo_name", "in": "path", "description": "Repository name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Repository deleted" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Repository not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/repositories/{repo_name}/tags": { "get": { "tags": [ "repositories" ], "operationId": "list_repo_tags", "parameters": [ { "name": "repo_name", "in": "path", "description": "Repository name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of tags in repository", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListRepoTagsResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Repository not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "repositories" ], "operationId": "create_repo_tag", "parameters": [ { "name": "repo_name", "in": "path", "description": "Repository name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRepoTagRequest" } } }, "required": true }, "responses": { "201": { "description": "Tag created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRepoTagResponse" } } } }, "400": { "description": "Invalid tag name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Repository or commit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Tag already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/repositories/{repo_name}/tags/{tag_name}": { "get": { "tags": [ "repositories" ], "operationId": "get_repo_tag", "parameters": [ { "name": "repo_name", "in": "path", "description": "Repository name", "required": true, "schema": { "type": "string" } }, { "name": "tag_name", "in": "path", "description": "Tag name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tag details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepoTagInfo" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Repository or tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "repositories" ], "operationId": "delete_repo_tag", "parameters": [ { "name": "repo_name", "in": "path", "description": "Repository name", "required": true, "schema": { "type": "string" } }, { "name": "tag_name", "in": "path", "description": "Tag name", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Tag deleted" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Repository or tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "patch": { "tags": [ "repositories" ], "operationId": "update_repo_tag", "parameters": [ { "name": "repo_name", "in": "path", "description": "Repository name", "required": true, "schema": { "type": "string" } }, { "name": "tag_name", "in": "path", "description": "Tag name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRepoTagRequest" } } }, "required": true }, "responses": { "204": { "description": "Tag updated" }, "400": { "description": "No updates provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Repository, tag, or commit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/repositories/{repo_name}/visibility": { "patch": { "tags": [ "repositories" ], "operationId": "set_repository_visibility", "parameters": [ { "name": "repo_name", "in": "path", "description": "Repository name", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetRepositoryVisibilityRequest" } } }, "required": true }, "responses": { "204": { "description": "Visibility updated" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Repository not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/system/version": { "get": { "tags": [], "operationId": "version_handler", "responses": { "200": { "description": "Version information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrchestratorVersion" } } } } } } }, "/api/v1/vm": { "get": { "tags": [ "vms" ], "operationId": "list_vms", "responses": { "200": { "description": "List all VMs accessible to the API key", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VM" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/branch/by_commit/{commit_id}": { "post": { "tags": [ "vm" ], "operationId": "branch_by_commit", "parameters": [ { "name": "commit_id", "in": "path", "description": "The commit id to branch off", "required": true, "schema": { "type": "string" } }, { "name": "count", "in": "query", "description": "Number of VMs to branch (optional; default 1)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "201": { "description": "Branch VM(s) created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "400": { "description": "Invalid VM ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/branch/by_ref/{repo_name}/{tag_name}": { "post": { "tags": [ "vm" ], "operationId": "branch_by_ref", "parameters": [ { "name": "repo_name", "in": "path", "description": "The repository name", "required": true, "schema": { "type": "string" } }, { "name": "tag_name", "in": "path", "description": "The tag name within the repository", "required": true, "schema": { "type": "string" } }, { "name": "count", "in": "query", "description": "Number of VMs to branch (optional; default 1)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "201": { "description": "Branch VM(s) created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "404": { "description": "Repository or tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/branch/by_tag/{tag_name}": { "post": { "tags": [ "vm" ], "operationId": "branch_by_tag", "parameters": [ { "name": "tag_name", "in": "path", "description": "The tag name to branch off", "required": true, "schema": { "type": "string" } }, { "name": "count", "in": "query", "description": "Number of VMs to branch (optional; default 1)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "201": { "description": "Branch VM(s) created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "404": { "description": "Tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/branch/by_vm/{vm_id}": { "post": { "tags": [ "vm" ], "operationId": "branch_by_vm", "parameters": [ { "name": "vm_id", "in": "path", "description": "VM to commit and then branch off of", "required": true, "schema": { "type": "string" } }, { "name": "keep_paused", "in": "query", "description": "If true, keep VM paused after commit", "required": false, "schema": { "type": "boolean" } }, { "name": "skip_wait_boot", "in": "query", "description": "If true, immediately return an error if VM is booting instead of waiting", "required": false, "schema": { "type": "boolean" } }, { "name": "count", "in": "query", "description": "Number of VMs to branch (optional; default 1)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "201": { "description": "Branch VM(s) created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "400": { "description": "Invalid VM ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/commits/{commit_id}/parents": { "get": { "tags": [ "commits" ], "operationId": "list_parent_commits", "parameters": [ { "name": "commit_id", "in": "path", "description": "Commit ID to start from", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of commits from the specified commit to the root", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VmCommitEntity" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Commit not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/from_commit": { "post": { "tags": [ "vm" ], "operationId": "restore_from_commit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FromCommitVmRequest" } } }, "required": true }, "responses": { "201": { "description": "VM restored from commit successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Cluster not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/new_root": { "post": { "tags": [ "vm" ], "operationId": "create_new_root_vm", "parameters": [ { "name": "wait_boot", "in": "query", "description": "If true, wait for the newly-created VM to finish booting before returning. Default: false.", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewRootRequest" } } }, "required": true }, "responses": { "201": { "description": "VM created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_id}": { "delete": { "tags": [ "vm" ], "operationId": "delete_vm", "parameters": [ { "name": "vm_id", "in": "path", "description": "VM ID to delete", "required": true, "schema": { "type": "string" } }, { "name": "skip_wait_boot", "in": "query", "description": "If true, return an error immediately if the VM is still booting. Default: false", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "VM deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmDeleteResponse" } } } }, "400": { "description": "Invalid VM ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_id}/commit": { "post": { "tags": [ "vm" ], "operationId": "commit_vm", "parameters": [ { "name": "vm_id", "in": "path", "description": "VM ID to commit", "required": true, "schema": { "type": "string" } }, { "name": "keep_paused", "in": "query", "description": "If true, keep VM paused after commit", "required": false, "schema": { "type": "boolean" } }, { "name": "skip_wait_boot", "in": "query", "description": "If true, return an error immediately if the VM is still booting. Default: false", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "description": "Optional commit metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmCommitRequest" } } }, "required": true }, "responses": { "201": { "description": "VM committed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmCommitResponse" } } } }, "400": { "description": "Invalid VM ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_id}/disk": { "patch": { "tags": [ "vm" ], "operationId": "resize_vm_disk", "parameters": [ { "name": "vm_id", "in": "path", "description": "VM ID whose disk to resize", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "skip_wait_boot", "in": "query", "description": "If true, return an error immediately if the VM is still booting. Default: false", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmResizeDiskRequest" } } }, "required": true }, "responses": { "200": { "description": "VM disk resized successfully" }, "400": { "description": "Invalid request (e.g. new size not larger than current)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_id}/exec": { "post": { "tags": [ "vm" ], "operationId": "exec_vm", "parameters": [ { "name": "vm_id", "in": "path", "description": "VM ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmExecRequest" } } }, "required": true }, "responses": { "200": { "description": "Command executed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmExecResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_id}/exec/stream": { "post": { "tags": [ "vm" ], "operationId": "exec_vm_stream", "parameters": [ { "name": "vm_id", "in": "path", "description": "VM ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmExecRequest" } } }, "required": true }, "responses": { "200": { "description": "NDJSON stream of stdout/stderr chunks" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_id}/exec/stream/attach": { "post": { "tags": [ "vm" ], "operationId": "exec_vm_stream_attach", "parameters": [ { "name": "vm_id", "in": "path", "description": "VM ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmExecStreamAttachRequest" } } }, "required": true }, "responses": { "200": { "description": "NDJSON stream replaying from cursor" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_id}/files": { "get": { "tags": [ "vm" ], "operationId": "read_file_vm", "parameters": [ { "name": "vm_id", "in": "path", "description": "VM ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "path", "in": "query", "description": "Absolute path of the file to read", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File contents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmReadFileResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "vm" ], "operationId": "write_file_vm", "parameters": [ { "name": "vm_id", "in": "path", "description": "VM ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmWriteFileRequest" } } }, "required": true }, "responses": { "200": { "description": "File written successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_id}/label": { "patch": { "tags": [ "vm" ], "operationId": "label_vm", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabelVmRequest" } } }, "required": true }, "responses": { "200": { "description": "Labels set successfully" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_id}/logs": { "get": { "tags": [ "vm" ], "operationId": "vm_logs", "parameters": [ { "name": "vm_id", "in": "path", "description": "VM ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offset", "in": "query", "description": "Byte offset into the log file (default: 0)", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "max_entries", "in": "query", "description": "Maximum number of log entries to return", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "stream", "in": "query", "description": "Filter by 'stdout' or 'stderr'", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exec logs retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmExecLogResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_id}/metadata": { "get": { "tags": [ "vm" ], "operationId": "get_vm_metadata", "parameters": [ { "name": "vm_id", "in": "path", "description": "VM ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "VM metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmMetadataResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_id}/ssh_key": { "get": { "tags": [ "vm" ], "operationId": "ssh_key", "parameters": [ { "name": "vm_id", "in": "path", "description": "Node ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List all VMs on node", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmSshKeyResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_id}/state": { "patch": { "tags": [ "vm" ], "operationId": "update_vm_state", "parameters": [ { "name": "vm_id", "in": "path", "description": "VM ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "skip_wait_boot", "in": "query", "description": "If true, error immediately if the VM is not finished booting. Defaults to false", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VmUpdateStateRequest" } } }, "required": true }, "responses": { "200": { "description": "VM state updated successfully" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_id}/status": { "get": { "tags": [ "vm" ], "operationId": "vm_status", "parameters": [ { "name": "vm_id", "in": "path", "description": "VM ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get status of a specific VM", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VM" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vm/{vm_or_commit_id}/branch": { "post": { "tags": [ "vm" ], "operationId": "branch_vm", "parameters": [ { "name": "vm_or_commit_id", "in": "path", "description": "Parent VM or commit ID", "required": true, "schema": { "type": "string" } }, { "name": "keep_paused", "in": "query", "description": "If true, keep VM paused after commit. Only applicable when branching a VM ID.", "required": false, "schema": { "type": "boolean" } }, { "name": "skip_wait_boot", "in": "query", "description": "If true, immediately return an error if VM is booting instead of waiting. Only applicable when branching a VM ID.", "required": false, "schema": { "type": "boolean" } }, { "name": "count", "in": "query", "description": "Number of VMs to branch (optional; default 1)", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "201": { "description": "Branch VM created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewVmsResponse" } } } }, "400": { "description": "Invalid VM ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "VM not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/vms": { "get": { "tags": [ "vms" ], "operationId": "list_vms", "responses": { "200": { "description": "List all VMs accessible to the API key", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/VM" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } } }, "components": { "schemas": { "BaseImageInfo": { "type": "object", "required": [ "base_image_id", "image_name", "owner_id", "is_public", "source_type", "size_mib", "created_at" ], "properties": { "base_image_id": { "type": "string" }, "created_at": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "image_name": { "type": "string" }, "is_public": { "type": "boolean" }, "owner_id": { "type": "string" }, "size_mib": { "type": "integer", "format": "int32" }, "source_type": { "type": "string" } } }, "BaseImageStatusResponse": { "type": "object", "required": [ "image_name", "status", "size_mib" ], "properties": { "error_message": { "type": [ "string", "null" ] }, "image_name": { "type": "string" }, "size_mib": { "type": "integer", "format": "int32" }, "status": { "type": "string" } } }, "CommitInfo": { "type": "object", "required": [ "commit_id", "owner_id", "name", "created_at", "is_public" ], "properties": { "commit_id": { "type": "string" }, "created_at": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "grandparent_commit_id": { "type": [ "string", "null" ] }, "is_public": { "type": "boolean" }, "name": { "type": "string" }, "owner_id": { "type": "string" }, "parent_vm_id": { "type": [ "string", "null" ] } } }, "CreateBaseImageRequest": { "type": "object", "required": [ "image_name", "source" ], "properties": { "description": { "type": [ "string", "null" ] }, "image_name": { "type": "string" }, "size_mib": { "type": "integer", "format": "int32", "description": "Additional capacity in MiB beyond the actual filesystem size (defaults to 256).\nThe final image size = calculated rootfs size + this value.\nSet to 0 for minimum possible image size, or higher for more free space." }, "source": { "$ref": "#/components/schemas/ImageSourceRequest" } } }, "CreateBaseImageResponse": { "type": "object", "required": [ "job_id", "image_name", "status" ], "properties": { "image_name": { "type": "string" }, "job_id": { "type": "string" }, "status": { "type": "string" } } }, "CreateDomainRequest": { "type": "object", "description": "Request body for POST /api/v1/domains", "required": [ "vm_id", "domain" ], "properties": { "domain": { "type": "string" }, "vm_id": { "type": "string", "format": "uuid" } } }, "CreateRepoTagRequest": { "type": "object", "description": "Request body for creating a tag within a repository: POST /api/v1/repositories/{repo_name}/tags", "required": [ "tag_name", "commit_id" ], "properties": { "commit_id": { "type": "string", "format": "uuid", "description": "The commit ID this tag should point to" }, "description": { "type": [ "string", "null" ], "description": "Optional description of what this tag represents" }, "tag_name": { "type": "string", "description": "The tag name (e.g. \"latest\", \"v1.0\")" } } }, "CreateRepoTagResponse": { "type": "object", "description": "Response body for POST /api/v1/repositories/{repo_name}/tags", "required": [ "tag_id", "reference", "commit_id" ], "properties": { "commit_id": { "type": "string", "format": "uuid", "description": "The commit ID this tag points to" }, "reference": { "type": "string", "description": "Full reference in image_name:tag format" }, "tag_id": { "type": "string", "format": "uuid", "description": "The ID of the newly created tag" } } }, "CreateRepositoryRequest": { "type": "object", "description": "Request body for POST /api/v1/repositories", "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Optional description of the repository" }, "name": { "type": "string", "description": "The name of the repository (alphanumeric, hyphens, underscores, dots, 1-64 chars)" } } }, "CreateRepositoryResponse": { "type": "object", "description": "Response body for POST /api/v1/repositories", "required": [ "repo_id", "name" ], "properties": { "name": { "type": "string", "description": "The name of the repository" }, "repo_id": { "type": "string", "format": "uuid", "description": "The ID of the newly created repository" } } }, "CreateTagRequest": { "type": "object", "description": "Request body for POST /api/v1/commit_tags", "required": [ "tag_name", "commit_id" ], "properties": { "commit_id": { "type": "string", "format": "uuid", "description": "The commit ID this tag should point to" }, "description": { "type": [ "string", "null" ], "description": "Optional description of what this tag represents" }, "tag_name": { "type": "string", "description": "The name of the tag (alphanumeric, hyphens, underscores, dots, 1-64 chars)" } } }, "CreateTagResponse": { "type": "object", "description": "Response body for POST /api/v1/commit_tags", "required": [ "tag_id", "tag_name", "commit_id" ], "properties": { "commit_id": { "type": "string", "format": "uuid", "description": "The commit ID this tag points to" }, "tag_id": { "type": "string", "format": "uuid", "description": "The ID of the newly created tag" }, "tag_name": { "type": "string", "description": "The name of the tag" } } }, "DeleteBaseImageResponse": { "type": "object", "required": [ "deleted", "base_image_id" ], "properties": { "base_image_id": { "type": "string" }, "deleted": { "type": "boolean" } } }, "DeleteDomainResponse": { "type": "object", "description": "Response body for DELETE /api/v1/domains/{domain_id}", "required": [ "domain_id" ], "properties": { "domain_id": { "type": "string", "format": "uuid" } } }, "DeployRequest": { "type": "object", "description": "Request body for `POST /api/v1/deploy`.", "required": [ "repo" ], "properties": { "branch": { "type": [ "string", "null" ], "description": "Git branch to clone (defaults to repo default branch)." }, "name": { "type": [ "string", "null" ], "description": "Optional project name (defaults to repo name)." }, "repo": { "type": "string", "description": "GitHub repository in `owner/repo` format." }, "settings": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeploySettings", "description": "Build/run settings." } ] } } }, "DeployResponse": { "type": "object", "description": "Response body for `POST /api/v1/deploy`.", "required": [ "project_id", "vm_id", "status" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "vm_id": { "type": "string", "format": "uuid" } } }, "DeploySettings": { "type": "object", "description": "Settings for the deploy build pipeline.", "properties": { "build_command": { "type": [ "string", "null" ] }, "install_command": { "type": [ "string", "null" ] }, "run_command": { "type": [ "string", "null" ] }, "working_directory": { "type": [ "string", "null" ] } } }, "DomainResponse": { "type": "object", "description": "Response type for domain operations.", "required": [ "domain_id", "vm_id", "domain", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "domain": { "type": "string" }, "domain_id": { "type": "string", "format": "uuid" }, "vm_id": { "type": "string", "format": "uuid" } } }, "EnvVarsResponse": { "type": "object", "description": "Response body for GET /env_vars and PUT /env_vars.", "required": [ "vars" ], "properties": { "vars": { "type": "object", "description": "All environment variables currently set for the authenticated user.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Reason of error" }, "success": { "type": "boolean", "description": "Is always: false" } } }, "ForkRepositoryRequest": { "type": "object", "description": "Request body for POST /api/v1/repositories/fork", "required": [ "source_org", "source_repo", "source_tag" ], "properties": { "repo_name": { "type": [ "string", "null" ], "description": "Name for the new repository in your org (defaults to source_repo if omitted)" }, "source_org": { "type": "string", "description": "The organization that owns the source public repository" }, "source_repo": { "type": "string", "description": "The source repository name" }, "source_tag": { "type": "string", "description": "The tag to fork (e.g. \"latest\", \"v1.0\")" }, "tag_name": { "type": [ "string", "null" ], "description": "Tag name in the new repo (defaults to source_tag if omitted)" } } }, "ForkRepositoryResponse": { "type": "object", "description": "Response body for POST /api/v1/repositories/fork", "required": [ "vm_id", "commit_id", "repo_name", "tag_name", "reference" ], "properties": { "commit_id": { "type": "string", "format": "uuid", "description": "The new commit in your org (snapshot of the forked VM)" }, "reference": { "type": "string", "description": "Full reference: repo_name:tag_name" }, "repo_name": { "type": "string", "description": "The new repository name in your org" }, "tag_name": { "type": "string", "description": "The tag name pointing to the forked commit" }, "vm_id": { "type": "string", "description": "The new VM that was created from the fork" } } }, "FromCommitVmRequest": { "oneOf": [ { "type": "object", "description": "The commit ID to restore from", "required": [ "commit_id" ], "properties": { "commit_id": { "type": "string", "format": "uuid", "description": "The commit ID to restore from" } } }, { "type": "object", "description": "The tag name to restore from (legacy org-scoped tag)", "required": [ "tag_name" ], "properties": { "tag_name": { "type": "string", "description": "The tag name to restore from (legacy org-scoped tag)" } } }, { "type": "object", "description": "A repository reference in \"repo_name:tag_name\" format", "required": [ "ref" ], "properties": { "ref": { "type": "string", "description": "A repository reference in \"repo_name:tag_name\" format" } } } ], "description": "Request body for POST /api/v1/vm/from_commit" }, "ImageSourceRequest": { "oneOf": [ { "type": "object", "required": [ "image_ref", "type" ], "properties": { "image_ref": { "type": "string" }, "type": { "type": "string", "enum": [ "docker" ] } } }, { "type": "object", "required": [ "bucket", "key", "type" ], "properties": { "bucket": { "type": "string" }, "key": { "type": "string" }, "type": { "type": "string", "enum": [ "s3" ] } } } ] }, "LabelVmRequest": { "type": "object", "properties": { "labels": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } } }, "ListBaseImagesResponse": { "type": "object", "required": [ "images", "total", "limit", "offset" ], "properties": { "images": { "type": "array", "items": { "$ref": "#/components/schemas/BaseImageInfo" } }, "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "ListCommitsResponse": { "type": "object", "required": [ "commits", "total", "limit", "offset" ], "properties": { "commits": { "type": "array", "items": { "$ref": "#/components/schemas/CommitInfo" } }, "limit": { "type": "integer", "format": "int64" }, "offset": { "type": "integer", "format": "int64" }, "total": { "type": "integer", "format": "int64" } } }, "ListPublicRepositoriesResponse": { "type": "object", "description": "Response body for GET /api/v1/public/repositories", "required": [ "repositories" ], "properties": { "repositories": { "type": "array", "items": { "$ref": "#/components/schemas/PublicRepositoryInfo" } } } }, "ListRepoTagsResponse": { "type": "object", "description": "Response body for GET /api/v1/repositories/{repo_name}/tags", "required": [ "repository", "tags" ], "properties": { "repository": { "type": "string", "description": "The repository name" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/RepoTagInfo" }, "description": "List of tags in this repository" } } }, "ListRepositoriesResponse": { "type": "object", "description": "Response body for GET /api/v1/repositories", "required": [ "repositories" ], "properties": { "repositories": { "type": "array", "items": { "$ref": "#/components/schemas/RepositoryInfo" }, "description": "List of all repositories in the user's organization" } } }, "ListTagsResponse": { "type": "object", "description": "Response body for GET /api/v1/commit_tags", "required": [ "tags" ], "properties": { "tags": { "type": "array", "items": { "$ref": "#/components/schemas/TagInfo" }, "description": "List of all tags in the user's organization" } } }, "NewRootRequest": { "type": "object", "required": [ "vm_config" ], "properties": { "vm_config": { "$ref": "#/components/schemas/VmCreateVmConfig" } } }, "NewVmResponse": { "type": "object", "description": "Response body for new VM requests (new_root, from_commit, branch)", "required": [ "vm_id" ], "properties": { "vm_id": { "type": "string" } } }, "NewVmsResponse": { "type": "object", "required": [ "vms" ], "properties": { "vms": { "type": "array", "items": { "$ref": "#/components/schemas/NewVmResponse" } } } }, "OrchestratorVersion": { "type": "object", "description": "Response struct for GET api/v1/system/version", "required": [ "executable_name", "workspace_version", "git_hash" ], "properties": { "executable_name": { "type": "string", "description": "Executable identifier; should be \"orchestrator\"" }, "git_hash": { "type": "string", "description": "Current git hash used for the build" }, "workspace_version": { "type": "string", "description": "Current workspace version" } } }, "PublicRepositoryInfo": { "type": "object", "description": "Public repository information (includes owner org name for namespacing)", "required": [ "repo_id", "org_name", "name", "full_name", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "When the repository was created" }, "description": { "type": [ "string", "null" ], "description": "Optional description" }, "full_name": { "type": "string", "description": "Full reference: org_name/repo_name" }, "name": { "type": "string", "description": "The repository name" }, "org_name": { "type": "string", "description": "The owning organization's name (namespace)" }, "repo_id": { "type": "string", "format": "uuid", "description": "The repository's unique identifier" } } }, "RepoTagInfo": { "type": "object", "description": "Tag information within a repository context", "required": [ "tag_id", "tag_name", "reference", "commit_id", "created_at", "updated_at" ], "properties": { "commit_id": { "type": "string", "format": "uuid", "description": "The commit ID this tag currently points to" }, "created_at": { "type": "string", "format": "date-time", "description": "When the tag was created" }, "description": { "type": [ "string", "null" ], "description": "Optional description" }, "reference": { "type": "string", "description": "Full reference in image_name:tag format" }, "tag_id": { "type": "string", "format": "uuid", "description": "The tag's unique identifier" }, "tag_name": { "type": "string", "description": "The tag name" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the tag was last updated" } } }, "RepositoryInfo": { "type": "object", "description": "Repository information returned in list and get operations", "required": [ "repo_id", "name", "is_public", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time", "description": "When the repository was created" }, "description": { "type": [ "string", "null" ], "description": "Optional description" }, "is_public": { "type": "boolean", "description": "Whether this repository is publicly visible" }, "name": { "type": "string", "description": "The repository name" }, "repo_id": { "type": "string", "format": "uuid", "description": "The repository's unique identifier" } } }, "SetEnvVarsRequest": { "type": "object", "description": "Request body for PUT /env_vars — sets (upserts) one or more environment variables.\n\n# Lifecycle model\n\nEnvironment variables are written to `/etc/environment` inside a VM **once\nat boot time** via a vsock `WriteFile` request. They are **not** live-synced\nto running VMs. This is intentional: VMs are ephemeral (create → use →\ndestroy/branch), so env var changes naturally take effect on the next VM.\n\nThe `replace` flag exists so callers can atomically express \"I want exactly\nthese variables and nothing else\" without having to DELETE each stale key\nindividually. Without it, the only way to remove a variable from future VMs\nis a separate `DELETE /env_vars/{key}` call per key.", "required": [ "vars" ], "properties": { "replace": { "type": "boolean", "description": "If true, delete all existing variables before writing the new set.\nThis gives \"set exactly these vars\" semantics. Default: false (upsert)." }, "vars": { "type": "object", "description": "Key-value pairs to set. Keys must be valid shell identifiers\n(`^[A-Za-z_][A-Za-z0-9_]*$`, max 256 chars). Values max 8192 chars.\n\nWhen `replace` is false (default): existing keys are overwritten, keys\nnot mentioned are left untouched (upsert semantics).\n\nWhen `replace` is true: all existing variables are deleted first, then\nonly the provided vars are stored (replace-all semantics).", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } } }, "SetRepositoryVisibilityRequest": { "type": "object", "description": "Request body for PATCH /api/v1/repositories/{repo_name}/visibility", "required": [ "is_public" ], "properties": { "is_public": { "type": "boolean", "description": "Whether the repository should be publicly visible" } } }, "TagInfo": { "type": "object", "description": "Tag information returned in list and get operations", "required": [ "tag_id", "tag_name", "commit_id", "created_at", "updated_at" ], "properties": { "commit_id": { "type": "string", "format": "uuid", "description": "The commit ID this tag currently points to" }, "created_at": { "type": "string", "format": "date-time", "description": "When the tag was created" }, "description": { "type": [ "string", "null" ], "description": "Optional description of what this tag represents" }, "tag_id": { "type": "string", "format": "uuid", "description": "The tag's unique identifier" }, "tag_name": { "type": "string", "description": "The name of the tag" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the tag was last updated (moved to different commit or description changed)" } } }, "UpdateCommitRequest": { "type": "object", "description": "Request body for PATCH /commits/{commit_id}", "required": [ "is_public" ], "properties": { "description": { "type": [ "string", "null" ], "description": "Optional description for the commit." }, "is_public": { "type": "boolean" }, "name": { "type": [ "string", "null" ], "description": "Optional human-readable name for the commit." } } }, "UpdateRepoTagRequest": { "type": "object", "description": "Request body for PATCH /api/v1/repositories/{repo_name}/tags/{tag_name}", "properties": { "commit_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional new commit ID to move the tag to" }, "description": { "type": [ "string", "null" ], "description": "Optional new description for the tag. Send `null` to clear." } } }, "UpdateTagRequest": { "type": "object", "description": "Request body for PATCH /api/v1/commit_tags/{tag_name}\n\nFor `description`:\n- Field absent from JSON → don't change the description\n- Field present as `null` → clear the description\n- Field present as `\"text\"` → set the description to \"text\"", "properties": { "commit_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional new commit ID to move the tag to" }, "description": { "type": [ "string", "null" ], "description": "Optional new description for the tag. Send `null` to clear an existing description." } } }, "UploadBaseImageResponse": { "type": "object", "required": [ "job_id", "image_name", "status" ], "properties": { "image_name": { "type": "string" }, "job_id": { "type": "string" }, "status": { "type": "string" } } }, "VM": { "type": "object", "required": [ "vm_id", "owner_id", "created_at", "state" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "labels": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "owner_id": { "type": "string", "format": "uuid" }, "state": { "$ref": "#/components/schemas/VmState" }, "vm_id": { "type": "string", "format": "uuid" } } }, "ValidateKeyResponse": { "type": "object", "description": "Response body for POST /api/keys/validate", "required": [ "valid", "message" ], "properties": { "message": { "type": "string" }, "valid": { "type": "boolean" } } }, "VmCommitEntity": { "type": "object", "required": [ "id", "owner_id", "name", "created_at", "is_public" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "grandparent_commit_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The commit that this commit's parent VM was started from, if any. Intended to optimize traversing the commit tree." }, "id": { "type": "string", "format": "uuid" }, "is_public": { "type": "boolean", "description": "Whether this commit is publicly accessible (readable/restorable by anyone)." }, "name": { "type": "string" }, "owner_id": { "type": "string", "format": "uuid", "description": "api key id." }, "parent_vm_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The VM that this commit was created from, if any." } } }, "VmCommitRequest": { "type": "object", "description": "The request body for POST /api/vm/{vm_id}/commit", "properties": { "commit_id": { "type": [ "string", "null" ], "format": "uuid", "description": "If provided, chelsea will use the requested commit UUID. Otherwise, it will generate a UUID itself." }, "description": { "type": [ "string", "null" ], "description": "Optional description for the commit." }, "name": { "type": [ "string", "null" ], "description": "Optional human-readable name for the commit. Defaults to auto-generated name if not provided." } } }, "VmCommitResponse": { "type": "object", "description": "The response body for POST /api/vm/{vm_id}/commit", "required": [ "commit_id" ], "properties": { "commit_id": { "type": "string", "format": "uuid", "description": "The UUID of the newly-created commit" } } }, "VmCreateVmConfig": { "type": "object", "description": "Struct representing configuration options common to all VMs", "properties": { "fs_size_mib": { "type": [ "integer", "null" ], "format": "int32", "description": "The disk size, in MiB.", "minimum": 0 }, "image_name": { "type": [ "string", "null" ], "description": "The filesystem base image name. Currently, must be 'default'" }, "kernel_name": { "type": [ "string", "null" ], "description": "The kernel name. Currently, must be 'default.bin'" }, "labels": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "mem_size_mib": { "type": [ "integer", "null" ], "format": "int32", "description": "The RAM size, in MiB.", "minimum": 0 }, "vcpu_count": { "type": [ "integer", "null" ], "format": "int32", "description": "How many vCPUs to allocate to this VM (and its children)", "minimum": 0 } } }, "VmDeleteResponse": { "type": "object", "description": "Response body for DELETE /api/vm/{vm_id}", "required": [ "vm_id" ], "properties": { "vm_id": { "type": "string" } } }, "VmExecLogEntry": { "type": "object", "description": "Individual log entry describing emitted stdout/stderr chunk.", "required": [ "timestamp", "stream", "data_b64" ], "properties": { "data_b64": { "type": "string", "description": "Base64-encoded bytes from stdout/stderr chunk." }, "exec_id": { "type": [ "string", "null" ], "format": "uuid" }, "stream": { "$ref": "#/components/schemas/VmExecLogStream" }, "timestamp": { "type": "string" } } }, "VmExecLogResponse": { "type": "object", "description": "Response for exec log tail requests.", "required": [ "entries", "next_offset", "eof" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/VmExecLogEntry" }, "description": "Returned log entries." }, "eof": { "type": "boolean", "description": "True when the end of file was reached." }, "next_offset": { "type": "integer", "format": "int64", "description": "Next byte offset to continue from.", "minimum": 0 } } }, "VmExecLogStream": { "type": "string", "description": "Streams available for exec logging.", "enum": [ "stdout", "stderr" ] }, "VmExecRequest": { "type": "object", "description": "Request body for POST /api/vm/{vm_id}/exec", "required": [ "command" ], "properties": { "command": { "type": "array", "items": { "type": "string" }, "description": "Command and arguments to execute." }, "env": { "type": [ "object", "null" ], "description": "Optional environment variables to set for the process.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "exec_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional exec identifier for tracking." }, "stdin": { "type": [ "string", "null" ], "description": "Optional stdin payload passed to the command." }, "timeout_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Timeout in seconds (0 = no timeout).", "minimum": 0 }, "working_dir": { "type": [ "string", "null" ], "description": "Optional working directory for the command." } } }, "VmExecResponse": { "type": "object", "description": "Response body for POST /api/vm/{vm_id}/exec", "required": [ "exit_code", "stdout", "stderr" ], "properties": { "exec_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Exec identifier associated with this run." }, "exit_code": { "type": "integer", "format": "int32", "description": "Exit code returned by the command." }, "stderr": { "type": "string", "description": "UTF-8 decoded stderr (lossy)." }, "stdout": { "type": "string", "description": "UTF-8 decoded stdout (lossy)." } } }, "VmExecStreamAttachRequest": { "type": "object", "description": "Request body for POST /api/vm/{vm_id}/exec/stream/attach", "required": [ "exec_id" ], "properties": { "cursor": { "type": [ "integer", "null" ], "format": "int64", "description": "Optional cursor to resume from (exclusive). If omitted, the full retained backlog is replayed.", "minimum": 0 }, "exec_id": { "type": "string", "format": "uuid", "description": "Identifier of the exec stream session to reattach to." }, "from_latest": { "type": [ "boolean", "null" ], "description": "Start streaming after the latest retained chunk (ignores cursor)." } } }, "VmMetadataResponse": { "type": "object", "description": "Response for GET /api/v1/vm/{vm_id}/metadata", "required": [ "vm_id", "owner_id", "created_at", "state", "ip" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "grandparent_vm_id": { "type": [ "string", "null" ], "format": "uuid" }, "ip": { "type": "string" }, "owner_id": { "type": "string", "format": "uuid" }, "parent_commit_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "$ref": "#/components/schemas/VmState" }, "vm_id": { "type": "string", "format": "uuid" } } }, "VmReadFileResponse": { "type": "object", "description": "Response body for GET /api/vm/{vm_id}/files", "required": [ "content_b64" ], "properties": { "content_b64": { "type": "string", "description": "File contents, base64-encoded." } } }, "VmResizeDiskRequest": { "type": "object", "description": "Request body for PATCH /api/vm/{vm_id}/disk", "required": [ "fs_size_mib" ], "properties": { "fs_size_mib": { "type": "integer", "format": "int32", "description": "The new disk size in MiB. Must be strictly greater than the current size.", "minimum": 0 } } }, "VmSshKeyResponse": { "type": "object", "description": "Response body for GET /api/vm/{vm_id}/ssh_key", "required": [ "ssh_private_key", "ssh_port" ], "properties": { "ssh_port": { "type": "integer", "format": "int32", "description": "The SSH port that will be DNAT'd to the VM's netns (and, in turn, to its TAP device)", "minimum": 0 }, "ssh_private_key": { "type": "string", "description": "Private SSH key in stringified OpenSSH format" } } }, "VmState": { "type": "string", "description": "The state of a VM", "enum": [ "booting", "running", "paused", "sleeping", "dead" ] }, "VmUpdateStateEnum": { "type": "string", "description": "Possible options for the state requested in PATCH /api/vm/{vm_id}/state", "enum": [ "Paused", "Running" ] }, "VmUpdateStateRequest": { "type": "object", "description": "Request body for PATCH /api/vm/{vm_id}/state", "required": [ "state" ], "properties": { "state": { "$ref": "#/components/schemas/VmUpdateStateEnum", "description": "The requested state for the VM" } } }, "VmWriteFileRequest": { "type": "object", "description": "Request body for PUT /api/vm/{vm_id}/files", "required": [ "path", "content_b64" ], "properties": { "content_b64": { "type": "string", "description": "File contents, base64-encoded." }, "create_dirs": { "type": "boolean", "description": "Create parent directories if they don't exist." }, "mode": { "type": "integer", "format": "int32", "description": "File mode (e.g. 0644). Defaults to 0644 if omitted.", "minimum": 0 }, "path": { "type": "string", "description": "Destination path on the VM." } } } }, "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer", "bearerFormat": "Token" } } } }