{ "openapi": "3.1.0", "info": { "title": "Vast.ai API", "description": "API for managing cloud GPU instances, volumes, and resources on Vast.ai", "version": "1.0.0", "contact": { "name": "Vast.ai Support", "url": "https://discord.gg/hSuEbSQ4X8" } }, "servers": [ { "url": "https://console.vast.ai", "description": "Production API server" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v0/network_disk/": { "post": { "summary": "add network-disk", "description": "Adds a network disk to be used to create network volume offers, or adds machines to an existing network disk.\nCLI Usage: vast add network_disk ... [options]", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mount_point" ], "properties": { "machine_id": { "type": "integer", "description": "ID of the machine to add network disk to" }, "machine_ids": { "type": "array", "items": { "type": "integer" }, "description": "IDs of machines to add network disk to" }, "mount_point": { "type": "string", "description": "Path to mount point of networked storage on machine or machines" }, "disk_id": { "type": "integer", "description": "ID of network disk, if adding machines to existing disk" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "disk_id": { "type": "integer", "description": "ID of disk created or added to machines" } }, "example": { "success": true, "disk_id": 2 } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "Invalid machine id" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_authorized" }, "msg": { "type": "string", "example": "Only machine owner can add network disk" } } } } } } }, "tags": [ "Network Volumes" ] } }, "/api/v0/instances/{id}/ssh/": { "post": { "summary": "attach ssh-key", "description": "Attaches an SSH key to the specified instance, allowing SSH access using the provided key.\n\nCLI Usage: vast attach instance_id ssh_key", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the instance to attach the SSH key to" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ssh_key": { "type": "string", "description": "The SSH key to attach to the instance", "example": "ssh-rsa AAAAB3NzaC1yc2EAAA..." } } } } } }, "responses": { "200": { "description": "SSH key attached successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "msg": { "type": "string", "example": "SSH key attached successfully" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "Instances" ] } }, "/api/v0/commands/copy_direct/": { "delete": { "summary": "cancel copy", "description": "Cancel a remote copy operation specified by the destination ID (dst_id).", "operationId": "cancelRemoteRsync", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dst_id": { "type": "string", "description": "ID of the copy instance target to cancel." } }, "required": [ "dst_id" ] } } } }, "responses": { "200": { "description": "Remote copy canceled successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Invalid arguments provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "Invalid dst_id." } } } } } }, "404": { "description": "Destination ID not found or access denied.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "no_such_user" }, "msg": { "type": "string", "example": "No such user." } } } } } } }, "security": [ { "BearerAuth": [] } ], "x-rateLimit": 3.5, "tags": [ "Instances" ] }, "put": { "summary": "copy", "description": "Initiate a remote copy operation to transfer data from one instance to another or between an instance and the local machine.", "operationId": "initiateRemoteRsync", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "src_id": { "type": "string", "description": "ID of the source instance." }, "dst_id": { "type": "string", "description": "ID of the destination instance." }, "src_path": { "type": "string", "description": "Path of the source data." }, "dst_path": { "type": "string", "description": "Path of the destination data." } }, "required": [ "src_path", "dst_path" ] } } } }, "responses": { "200": { "description": "Remote copy initiated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "msg": { "type": "string", "example": "Remote to Remote copy initiated - check instance status bar for progress updates (~30 seconds delayed)." } } } } } }, "400": { "description": "Invalid arguments provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "Invalid src_path." } } } } } }, "404": { "description": "Source or destination ID not found or access denied.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "no_such_user" }, "msg": { "type": "string", "example": "No such user." } } } } } } }, "security": [ { "BearerAuth": [] } ], "x-rateLimit": 3.5, "tags": [ "Instances" ] } }, "/api/v0/machines/{machine_id}/cancel_maint": { "put": { "summary": "cancel maint", "description": "Cancel a scheduled maintenance window for a specified machine.", "parameters": [ { "name": "machine_id", "in": "path", "required": true, "description": "ID of the machine to cancel maintenance for.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Maintenance window successfully canceled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "ctime": { "type": "number", "format": "float", "description": "Current time in seconds since the epoch." }, "machine_id": { "type": "integer", "description": "ID of the machine." }, "msg": { "type": "string", "example": "deleted 1 scheduled maintenance window(s) on machine 1234" } } } } } }, "404": { "description": "Machine not found or does not belong to the user.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "msg": { "type": "string", "example": "No such machine id" }, "machine_id": { "type": "integer" }, "user_id": { "type": "integer" } } } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "Machines" ] } }, "/api/v0/commands/rclone/": { "delete": { "summary": "cancel sync", "description": "Cancels an in-progress remote sync operation identified by the destination instance ID.\nThis operation cannot be resumed once canceled and must be restarted if needed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dst_id": { "type": "integer", "description": "The destination instance ID of the sync operation to cancel." } }, "required": [ "dst_id" ] } } } }, "responses": { "200": { "description": "Sync operation canceled successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "msg": { "type": "string", "example": "Remote copy canceled - check instance status bar for progress updates (~30 seconds delayed)." } } } } } }, "400": { "description": "Invalid request due to missing or incorrect parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "Invalid dst_id." } } } } } }, "404": { "description": "Instance not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "no_such_instance" }, "msg": { "type": "string", "example": "No such instance." } } } } } } }, "tags": [ "Instances" ] }, "post": { "summary": "cloud copy", "description": "Starts a cloud copy operation by sending a command to the remote server. The operation can transfer data between an instance and a cloud service.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance_id": { "type": "string", "description": "ID of the instance." }, "src": { "type": "string", "description": "Source path for the copy operation." }, "dst": { "type": "string", "description": "Destination path for the copy operation." }, "selected": { "type": "string", "description": "ID of the cloud connection." }, "transfer": { "type": "string", "description": "Type of transfer (e.g., \"Instance To Cloud\" or \"Cloud To Instance\")." }, "flags": { "type": "array", "items": { "type": "string" }, "description": "Additional flags for the operation." }, "api_key": { "type": "string", "description": "API key for authentication." } } } } } }, "responses": { "200": { "description": "Cloud copy operation initiated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "msg": { "type": "string" }, "result_url": { "type": "string" } } } } } }, "400": { "description": "Bad request due to invalid parameters or cloud service.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "msg": { "type": "string" } } } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "Instances" ] } }, "/api/v0/instances/bid_price/{id}/": { "put": { "summary": "change bid", "description": "Change the current bid price of an instance to a specified price.\nCLI Usage: vastai change bid id [--price PRICE]", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Instance ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "client_id", "price" ], "properties": { "client_id": { "type": "string", "description": "Client identifier (usually \"me\")", "example": "me" }, "price": { "type": "number", "description": "Bid price in $/hour", "minimum": 0.001, "maximum": 32.0, "example": 0.17 } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "enum": [ "invalid_args" ] }, "msg": { "type": "string", "example": "Please set a bid price >= 0.001." } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "enum": [ "no_such_instance" ] }, "msg": { "type": "string", "example": "Instance with that ID does not exist." } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=5.5" } } } } } } }, "tags": [ "Instances" ] } }, "/api/v0/machines/{machine_id}/cleanup": { "put": { "summary": "cleanup machine", "description": "This endpoint removes expired contracts on a specified machine, freeing up space.\n\nCLI Usage: vast-ai cleanup machine {machine_id}", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "machine_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The ID of the machine to clean up." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "An empty JSON object is expected." } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "ctime": { "type": "number", "format": "float", "example": 1633036800.0 }, "machine_id": { "type": "integer", "example": 123 }, "user_id": { "type": "integer", "example": 456 }, "num_deleted": { "type": "integer", "example": 5 }, "msg": { "type": "string", "example": "deleted 5 expired contracts on machine 123" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=8" } } } } } } }, "tags": [ "Machines" ] } }, "/api/v0/auth/apikeys/": { "post": { "summary": "create api-key", "description": "Creates a new API key with specified permissions for the authenticated user.\n\nCLI Usage: vast create api-key --name NAME --permission_file PERMISSIONS [--key_params PARAMS]\n\nExample:\nvast create api-key --name \"read-only\" --permission_file permissions.json", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name for the API key", "example": "read-only-key" }, "permissions": { "type": "object", "description": "JSON object containing permission definitions", "example": { "read": true, "write": false } }, "key_params": { "type": "object", "description": "Optional wildcard parameters for advanced keys", "example": { "ip_whitelist": [ "1.2.3.4" ] } } } } } } }, "responses": { "200": { "description": "API key created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the created API key", "example": 12345 }, "key": { "type": "string", "description": "The newly generated API key", "example": "vast-123456789abcdef" }, "permissions": { "anyOf": [ { "type": "boolean", "description": "False when permissions are disabled", "example": false }, { "type": "object", "description": "Object defining the permissions when enabled", "example": { "read": true, "write": false } } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "enum": [ "invalid_permissions", "missing_permissions" ] }, "msg": { "type": "string", "example": "Invalid permission format" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "msg": { "type": "string", "example": "Unauthorized" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=2.0" } } } } } } }, "tags": [ "Accounts" ] }, "get": { "summary": "show api keys", "description": "Retrieves all API keys associated with the authenticated user.\n\nCLI Usage: vastai show api-keys", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "API keys successfully retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "apikeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "user_id": { "type": "integer", "example": 456 }, "key": { "type": "string", "example": "your-api-key-value" }, "rights": { "type": "string", "example": "read" }, "team_id": { "type": "integer", "example": 789 }, "team_name": { "type": "string", "example": "Team Alpha" } } } } } } } } }, "400": { "description": "Bad Request - API Key not provided or not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "API Key not provided as bearer token." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=1.0" } } } } } } }, "tags": [ "Accounts" ] } }, "/api/v0/workergroups/": { "post": { "summary": "create workergroup", "description": "Creates a new workergroup configuration that manages worker instances for a serverless endpoint.\n\nCLI Usage: vast-ai create workergroup --template_hash --endpoint_name [options]", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint_name": { "type": "string", "description": "Name of the endpoint group", "example": "vLLM-Qwen3-8B" }, "endpoint_id": { "type": "integer", "description": "ID of existing endpoint group (alternative to endpoint_name)", "example": 123 }, "template_hash": { "type": "string", "description": "Hash ID of template to use for worker instances", "example": "abc123def456" }, "template_id": { "type": "integer", "description": "ID of template (alternative to template_hash)", "example": 456 }, "search_params": { "type": "string", "description": "Search query for finding worker instances (alternative to template)", "default": "verified=true rentable=true rented=false", "example": "gpu_name=RTX_3090 rentable=true" }, "launch_args": { "type": "string", "description": "Additional launch arguments for worker instances", "example": "--env VAR=value" }, "min_load": { "type": "number", "description": "Minimum load threshold for scaling", "default": 1.0, "example": 1.0 }, "target_util": { "type": "number", "description": "Target GPU utilization", "default": 0.9, "example": 0.9 }, "cold_mult": { "type": "number", "description": "Cold start multiplier", "default": 3.0, "example": 3.0 }, "cold_workers": { "type": "integer", "description": "Number of cold workers to maintain", "default": 3, "example": 3 }, "max_workers": { "type": "integer", "description": "Maximum number of worker instances", "default": 20, "example": 20 }, "test_workers": { "type": "integer", "description": "Number of test workers", "default": 3, "example": 3 }, "gpu_ram": { "type": "integer", "description": "Minimum GPU RAM in GB", "default": 24, "example": 24 } } } } } }, "responses": { "200": { "description": "Successfully created workergroup", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "id": { "type": "integer", "description": "ID of created autoscaling job", "example": 789 } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "enum": [ "invalid_args" ] }, "msg": { "type": "string", "example": "Please assign your workergroup to a valid endpoint identifier" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=4.0" } } } } } } }, "tags": [ "Serverless" ] }, "get": { "summary": "show workergroup", "description": "Retrieves the list of workergroups associated with the authenticated user.\n\nCLI Usage: vastai show workergroups", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "min_load": { "type": "number", "example": 1.0 }, "target_util": { "type": "number", "example": 0.9 }, "cold_mult": { "type": "number", "example": 3.0 }, "test_workers": { "type": "integer", "example": 3 }, "template_hash": { "type": "string", "example": "abc123def456" }, "template_id": { "type": "integer", "example": 456 }, "search_query": { "type": "object", "description": "Parsed search parameters as JSON object", "example": "verified=true rentable=true rented=false" }, "launch_args": { "type": "string", "example": "--env VAR=value" }, "gpu_ram": { "type": "number", "example": 24 }, "endpoint_name": { "type": "string", "example": "my_endpoint" }, "endpoint_id": { "type": "integer", "example": 789 }, "api_key": { "type": "string", "example": "your_api_key_here" }, "created_at": { "type": "string", "format": "date-time", "example": "2023-10-01T12:00:00Z" }, "user_id": { "type": "integer", "example": 456 } } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "msg": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "msg": { "type": "string" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=2.0" } } } } } } }, "tags": [ "Serverless" ] } }, "/api/v0/endptjobs/": { "post": { "summary": "create endpoint", "description": "This endpoint creates a new job processing endpoint with specified parameters.\n\nCLI Usage: vast-ai create endpoint", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "min_load": { "type": "number", "description": "Minimum load for the endpoint.", "default": 10.0, "example": 50.0 }, "target_util": { "type": "number", "description": "Target utilization for the endpoint.", "default": 0.9, "example": 0.75 }, "cold_mult": { "type": "number", "description": "Multiplier for cold start.", "default": 2.5, "example": 2.0 }, "cold_workers": { "type": "integer", "description": "Number of cold workers.", "default": 5, "example": 5 }, "max_workers": { "type": "integer", "description": "Maximum number of workers.", "default": 20, "example": 20 }, "endpoint_name": { "type": "string", "description": "Name of the endpoint.", "default": "default-endpoint", "example": "my_endpoint" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "result": { "type": "integer", "description": "The ID of the created endpoint", "example": 12345 } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error", "properties": { "error": { "type": "string", "enum": [ "invalid_args" ] } } } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=4.0" } } } } } } }, "tags": [ "Serverless" ] }, "get": { "summary": "show endpoints", "description": "Retrieve a list of endpoint jobs for the authenticated user.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "A list of endpoint jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "min_load": { "type": "number", "example": 0.0 }, "target_util": { "type": "number", "example": 0.9 }, "cold_mult": { "type": "number", "example": 2.5 }, "cold_workers": { "type": "integer", "example": 5 }, "max_workers": { "type": "integer", "example": 20 }, "endpoint_name": { "type": "string", "example": "vLLM-Qwen3-8B" }, "api_key": { "type": "string", "example": "your_api_key_here" }, "user_id": { "type": "integer", "example": 456 }, "created_at": { "type": "string", "format": "date-time", "example": "2023-10-01T12:00:00Z" }, "endpoint_state": { "type": "string", "example": "active" } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "No endpoints for user found" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "msg": { "type": "string" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=3.0" } } } } } } }, "tags": [ "Serverless" ] } }, "/api/v0/secrets/": { "post": { "summary": "create env-var", "description": "Creates a new encrypted environment variable for the authenticated user.\nKeys are automatically converted to uppercase. Values are encrypted before storage.\nThere is a limit on the total number of environment variables per user.\n\nCLI Usage: vast create env-var KEY VALUE", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "description": "Environment variable key name (will be converted to uppercase)", "example": "API_TOKEN" }, "value": { "type": "string", "description": "Secret value to be encrypted and stored", "pattern": "^[a-zA-Z0-9_\\-\\.]+$", "example": "abc123xyz" } } } } } }, "responses": { "200": { "description": "Environment variable created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "msg": { "type": "string", "example": "Environment variable added successfully" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "enum": [ "missing_input", "max_secrets", "existing_key" ] }, "msg": { "type": "string", "example": "Both 'key' and 'value' are required." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - User is blacklisted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=3.0" } } } } } } }, "tags": [ "Accounts" ] }, "delete": { "summary": "delete env var", "description": "Deletes an environment variable associated with the authenticated user.\nThe variable must exist and belong to the requesting user.\n\nCLI Usage: vastai delete env-var ", "operationId": "deleteUserSecret", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Name of the environment variable to delete", "example": "MY_API_KEY" } } } } } }, "responses": { "200": { "description": "Environment variable deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad request - missing or invalid input", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "string", "enum": [ "missing_input", "nonexistent_key" ], "example": "missing_input" } } } ] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - User is blacklisted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests - rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=3.0" } } } } } } }, "tags": [ "Accounts" ] }, "get": { "summary": "show env vars", "description": "Retrieve a list of environment variables (secrets) for the authenticated user.\n\nCLI Usage: vast-ai show env-vars [-s]", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success response with user secrets", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "secrets": { "type": "object", "additionalProperties": { "type": "string", "example": "*****" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=5.0" } } } } } } }, "tags": [ "Accounts" ] }, "put": { "summary": "update env var", "description": "Updates the value of an existing environment variable for the authenticated user.\n\nCLI Usage: vast-ai set env-var KEY VALUE", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "description": "The key of the environment variable to update (will be converted to uppercase)", "example": "MY_API_KEY", "pattern": "^[a-zA-Z_]\\w*$" }, "value": { "type": "string", "description": "The new value for the environment variable", "example": "xyz123" } } } } } }, "responses": { "200": { "description": "Environment variable updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "msg": { "type": "string", "example": "Environment variable updated successfully" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ], "properties": { "error": { "type": "string", "enum": [ "missing_input", "empty_input", "input_too_long", "invalid_characters", "nonexistent_key" ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=3.0" } } } } } } }, "tags": [ "Accounts" ] } }, "/api/v0/asks/{id}/": { "put": { "summary": "create instance", "description": "Creates a new instance by accepting an \"ask\" contract from a provider. This is the main endpoint for launching new instances on Vast.ai.\nCLI Usage: vast create instance [options]", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the offer to accept" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template_id": { "type": "integer", "description": "Optional template ID to use for instance configuration", "example": 89 }, "template_hash_id": { "type": "string", "description": "Optional template hash ID to use for instance configuration", "example": "abc123def456" }, "image": { "type": "string", "description": "Docker image to use for the instance", "example": "tensorflow/tensorflow:latest-gpu", "maxLength": 1024 }, "disk": { "type": "number", "description": "Storage space in GB", "minimum": 8.0, "default": 10.0, "example": 32.0 }, "env": { "type": "object", "description": "Environment variables and port mappings", "example": { "JUPYTER_TOKEN": "abc123", "PORTAL_CONFIG": "{\"ports\": [8080, 8081]}" }, "maxLength": 256 }, "runtype": { "type": "string", "description": "Instance run type", "enum": [ "ssh", "jupyter", "args", "ssh_proxy", "ssh_direct", "jupyter_proxy", "jupyter_direct" ], "example": "jupyter" }, "onstart": { "type": "string", "description": "Commands to run when instance starts", "maxLength": 4096, "example": "pip install -r requirements.txt" }, "label": { "type": "string", "description": "User-defined label for the instance", "maxLength": 256, "example": "training-job-1" }, "image_login": { "type": "string", "description": "Docker registry credentials if needed", "example": "-u username -p password docker.io" }, "price": { "type": "number", "description": "Bid price per hour for interruptible instances", "minimum": 0.001, "maximum": 128.0, "example": 0.4 }, "target_state": { "type": "string", "description": "Desired initial state of the instance", "enum": [ "running", "stopped" ], "default": "running", "example": "running" }, "cancel_unavail": { "type": "boolean", "description": "Whether to cancel if instance cannot start immediately. Defaults to false for interruptibles, true for on-demand with target_state='running'", "example": true }, "vm": { "type": "boolean", "description": "Whether this is a VM instance", "default": false }, "client_id": { "type": "string", "description": "Client identifier (usually \"me\")", "example": "me" }, "apikey_id": { "type": "string", "description": "Optional API key identifier for audit logging" }, "args": { "type": "array", "items": { "type": "string" }, "description": "Arguments to pass to the container entrypoint", "example": [ "-c", "echo hello; sleep infinity;" ] }, "entrypoint": { "type": "string", "description": "Override entrypoint for args launch instance", "example": "bash" }, "use_ssh": { "type": "boolean", "description": "Launch as an SSH instance type (deprecated, use runtype instead)" }, "python_utf8": { "type": "boolean", "description": "Set python's locale to C.UTF-8" }, "lang_utf8": { "type": "boolean", "description": "Install and generate locales before instance launch, set locale to C.UTF-8" }, "use_jupyter_lab": { "type": "boolean", "description": "Launch instance with jupyter lab instead of notebook" }, "jupyter_dir": { "type": "string", "description": "Directory in instance to use to launch jupyter" }, "force": { "type": "boolean", "description": "Skip sanity checks when creating from an existing instance" }, "user": { "type": "string", "description": "User to use with docker create (breaks some images, use with caution)" }, "volume_info": { "type": "object", "description": "Volume creation/linking information", "properties": { "create_new": { "type": "boolean", "description": "Whether to create a new volume" }, "volume_id": { "type": "integer", "description": "ID of existing volume to link or volume offer ID for new volume" }, "size": { "type": "integer", "description": "Size of the volume in GB (for new volumes)" }, "mount_path": { "type": "string", "description": "Mount path for the volume inside the container" }, "name": { "type": "string", "description": "Label for the new volume" } } } } } } } }, "responses": { "200": { "description": "Instance created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "new_contract": { "type": "integer", "description": "ID of the newly created instance contract", "example": 1234568 } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "enum": [ "invalid_args", "invalid_price", "no_ssh_key_for_vm" ] }, "msg": { "type": "string", "example": "error 400/3467: Invalid args: 'id' is required and must be a valid offer ID" }, "ask_id": { "type": "integer", "example": 1234567 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "error 403/3586: Offer 1234567 is not your own. Hosts can only rent their own machines." }, "ask_id": { "type": "integer", "example": 1234567 } } } } } }, "404": { "description": "Offer not found or not available", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "error 404/3603: no_such_ask Instance type by id 1234567 is not available." }, "ask_id": { "type": "integer", "example": 1234567 } } } } } }, "410": { "description": "Offer no longer available (when cancel_unavail is true and instance cannot start)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "no_such_ask" }, "msg": { "type": "string", "example": "error 410/3907: no_such_ask Instance type 1234567 is no longer available." }, "ask_id": { "type": "integer", "example": 1234567 } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=4.5" } } } } } } }, "tags": [ "Instances" ] } }, "/api/v0/network_volume/": { "put": { "summary": "create network-volume", "description": "Creates a network volume from an offer\nCLI Usage: vast create network-volume ", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "size" ], "properties": { "id": { "type": "integer", "description": "ID of network volume ask being accepted" }, "size": { "type": "integer", "description": "size of network volume in GB being created" }, "name": { "type": "string", "description": "optional name for network volume being created" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "volume_name": { "type": "string", "description": "name of network volume created" }, "volume_size": { "type": "integer", "description": "size of network volume created" } }, "example": { "success": true, "id": 6, "msg": "Deleted network volume listing" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "You must pass in `id` in the body of the request" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_authorized" }, "msg": { "type": "string", "example": "Authorization Error. Check that you have proper privileges to perform this action." } } } } } } }, "tags": [ "Network Volumes" ] }, "post": { "summary": "list network-volume", "description": "Lists a network disk for rent as network volumes, or updates an existing listing with a new price/size/end date/discount\nCLI Usage: vast list network-volume [options]", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "disk_id" ], "properties": { "price_disk": { "type": "number", "format": "float", "description": "Price per GB of network volume storage" }, "disk_id": { "type": "integer", "description": "ID of network disk for which offer is being created" }, "size": { "type": "integer", "description": "Size in GB of the amount of space available to be rented" }, "credit_discount_max": { "type": "number", "format": "float", "description": "Maximum discount rate allowed for prepaid credits" }, "end_date": { "type": "number", "format": "float", "description": "Unix timestamp for when the listing expires" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "msg": { "type": "string", "description": "status message" } }, "example": { "success": true, "disk_id": "created network volume ask with id 6 and size 24" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "Invalid disk_id" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "not_authorized" }, "msg": { "type": "string", "example": "Could not find network disk with id 6 associated with user" } } } } } } }, "tags": [ "Network Volumes" ] } }, "/api/v0/ssh/": { "post": { "summary": "create ssh-key", "description": "Creates a new SSH key and associates it with your account.\nThe key will be automatically added to all your current instances.\n\nCLI Usage: vast create ssh-key \nExample: vast create ssh-key \"ssh-rsa AAAAB3NzaC1...\"", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ssh_key" ], "properties": { "ssh_key": { "type": "string", "description": "The public SSH key to add (from .pub file)", "example": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC..." } } } } } }, "responses": { "200": { "description": "SSH key created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "key": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the created SSH key", "example": 123 }, "user_id": { "type": "integer", "description": "The user ID who owns the key", "example": 456 }, "public_key": { "type": "string", "description": "The public SSH key content", "example": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC..." }, "created_at": { "type": "string", "format": "date-time", "example": "2023-01-01T12:00:00Z" }, "deleted_at": { "type": "string", "format": "date-time", "nullable": true, "example": null } } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "enum": [ "no_ssh_key" ] }, "msg": { "type": "string", "example": "No ssh key provided" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=1.0" } } } } } } }, "tags": [ "Accounts" ] }, "get": { "summary": "show ssh keys", "description": "Retrieve a list of SSH keys associated with the authenticated user's account.", "operationId": "getSshKeysUser", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token for user authentication.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of SSH keys.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique identifier of the SSH key." }, "user_id": { "type": "integer", "description": "The ID of the user to whom the SSH key belongs." }, "key": { "type": "string", "description": "The SSH public key." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp when the SSH key was created." }, "deleted_at": { "type": "string", "format": "date-time", "nullable": true, "description": "The timestamp when the SSH key was deleted, if applicable." } } } } } } }, "401": { "description": "Unauthorized access due to invalid or missing authentication token." }, "404": { "description": "No SSH keys found for the user." } }, "security": [ { "BearerAuth": [] } ], "tags": [ "Accounts" ] } }, "/api/v0/users/": { "post": { "summary": "create subaccount", "description": "Creates either a standalone user account or a subaccount under a parent account.\nSubaccounts can be restricted to host-only functionality.\n\nCLI Usage: vastai create subaccount --email EMAIL --username USERNAME --password PASSWORD --type host", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "username", "password" ], "properties": { "email": { "type": "string", "description": "User's email address", "maxLength": 64, "example": "user@example.com", "pattern": "^(?!.*@vast)[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" }, "username": { "type": "string", "description": "Desired username", "maxLength": 64, "example": "testuser123" }, "password": { "type": "string", "description": "Account password", "maxLength": 256, "example": "securepass123" }, "host_only": { "type": "boolean", "description": "If true, account is restricted to host functionality only", "example": true }, "parent_id": { "type": "string", "description": "Parent account ID for subaccounts. Use \"me\" for current user.", "example": "me" }, "ssh_key": { "type": "string", "description": "Optional SSH public key", "maxLength": 4096 }, "captcha": { "type": "string", "description": "Captcha token (required for non-subaccounts)", "maxLength": 8192 } } } } } }, "responses": { "200": { "description": "Account created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "User ID" }, "username": { "type": "string" }, "email": { "type": "string" }, "api_key": { "type": "string", "description": "API key for the new account" } }, "example": { "id": 12345, "username": "testuser", "email": "user@example.com", "api_key": "abc123def456" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "invalid_email", "invalid_request", "missing_auth_value" ] }, "msg": { "type": "string" } }, "example": { "error": "invalid_email", "msg": "Email address not allowed" } } } } }, "403": { "description": "Forbidden - billing blacklisted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "User already exists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "user_exists" ] }, "msg": { "type": "string" } }, "example": { "error": "user_exists", "msg": "user already exists." } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=3.0" } } } } } } }, "tags": [ "Accounts" ] }, "put": { "summary": "set user", "description": "Updates the user data for the authenticated user.\n\nCLI Usage: vast set user --file {file_path}", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "normalized_email": { "type": "string", "description": "Normalized email address.", "example": "user@example.com" }, "username": { "type": "string", "description": "Username of the user.", "example": "johndoe" }, "fullname": { "type": "string", "description": "Full name of the user.", "example": "John Doe" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" } ], "properties": { "error": { "type": "string", "enum": [ "missing_input", "empty_input", "input_too_long", "invalid_characters", "nonexistent_key" ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=5.0" } } } } } } }, "tags": [ "Accounts" ] } }, "/api/v0/team": { "post": { "summary": "create team", "description": "Creates a new team with the authenticated user as the owner. The user's existing API key\nbecomes the owner key for the team. The user cannot already be a team or be a member of another team.\n\nThe operation:\n1. Converts the user into a team\n2. Creates default team roles (member, manager, owner)\n3. Converts user's API key into the owner key\n4. Adds the creating user as a team member\n\nCLI Usage: vast create team --name ", "security": [ { "BearerAuth": [] } ], "tags": [ "Team" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "team_name", "permissions" ], "properties": { "team_name": { "type": "string", "description": "Name for the new team", "example": "my-awesome-team" }, "permissions": { "type": "object", "description": "JSON object containing role and permission definitions. https://vast.ai/docs/cli/roles-and-permissions", "example": { "api": { "misc": {}, "user_read": {}, "instance_read": {}, "instance_write": {}, "billing_read": {}, "billing_write": {} } } } } } } } }, "responses": { "200": { "description": "Team created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Team Successfully Created!" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "enum": [ "already_team", "team_member" ] }, "msg": { "type": "string", "example": "Cannot create a team within a team" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - User is blacklisted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User's master API key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v0/team/role": { "post": { "summary": "create team role", "description": "Creates a new role within a team. Only team owners or managers with the appropriate permissions can perform this operation.\n\nCLI Usage: vast create team role --name --permissions ", "security": [ { "BearerAuth": [] } ], "tags": [ "Team" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "permissions" ], "properties": { "name": { "type": "string", "description": "Name for the new role", "example": "developer" }, "permissions": { "type": "object", "description": "JSON object containing permission definitions", "example": { "api": { "user_read": {}, "instance_write": {} } } } } } } } }, "responses": { "200": { "description": "Role created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "Role Successfully Created!" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "invalid_role_name" }, "msg": { "type": "string", "example": "Role name is invalid" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - User lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v0/template/": { "post": { "summary": "create template", "description": "Creates a new template for launching instances. If an identical template already exists,\nreturns the existing template instead of creating a duplicate.\n\nCLI Usage: vast create template [options]", "tags": [ "Templates" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "Docker image path", "example": "ghcr.io/huggingface/text-generation-inference:1.0.3" }, "tag": { "type": "string", "description": "Docker image tag" }, "env": { "type": "string", "description": "Docker environment variables and run arguments", "example": "-p 3000:3000 -e MODEL_ARGS='--model-id TheBloke/Llama-2-7B-chat-GPTQ'" }, "onstart": { "type": "string", "description": "Command to run on instance startup" }, "jup_direct": { "type": "boolean", "description": "Enable direct Jupyter connection" }, "ssh_direct": { "type": "boolean", "description": "Enable direct SSH connection" }, "use_jupyter_lab": { "type": "boolean", "description": "Use JupyterLab instead of Jupyter Notebook" }, "runtype": { "type": "string", "enum": [ "jupyter", "ssh", "args" ], "description": "Type of instance runtime" }, "use_ssh": { "type": "boolean", "description": "Enable SSH access" }, "jupyter_dir": { "type": "string", "description": "Jupyter notebook directory" }, "docker_login_repo": { "type": "string", "description": "Docker repository requiring authentication" }, "extra_filters": { "type": "object", "description": "Additional machine search filters" }, "recommended_disk_space": { "type": "number", "description": "Recommended disk space in GB" } }, "required": [ "image" ] } } } }, "responses": { "200": { "description": "Template created or existing template found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether operation was successful" }, "msg": { "type": "string", "description": "Status message" }, "template": { "type": "object", "description": "Template details", "properties": { "id": { "type": "integer", "description": "Template ID" }, "hash_id": { "type": "string", "description": "Template hash identifier" } } } } } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "msg": { "type": "string", "example": "Template Failed to be Created" } } } } } }, "429": { "description": "Rate limit exceeded" }, "401": { "description": "Unauthorized - invalid or missing API key" } } }, "get": { "summary": "search templates", "description": "Searches for templates based on query parameters and retrieves matching templates.\n\nCLI Usage: vast search templates", "parameters": [ { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search query string to match against template fields." }, { "name": "select_filters", "in": "query", "required": false, "schema": { "type": "object" }, "description": "Filters to apply on the search results." }, { "name": "order_by", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Column to order the results by." } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved templates", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "templates_found", "templates" ], "properties": { "success": { "type": "boolean", "example": true }, "templates_found": { "type": "integer", "description": "Number of templates found.", "example": 5 }, "templates": { "type": "array", "description": "List of templates matching the search criteria.", "items": { "$ref": "#/components/schemas/Template" } } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=3.0" } } } } } } }, "tags": [ "Search" ] } }, "/api/v0/auth/apikeys/{id}/": { "delete": { "summary": "delete api key", "description": "Deletes an existing API key belonging to the authenticated user.\nThe API key is soft-deleted by setting a deleted_at timestamp.\n\nCLI Usage: vastai delete api-key ID", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the API key to delete", "schema": { "type": "integer", "minimum": 1 }, "example": 123 } ], "responses": { "200": { "description": "API key successfully deleted", "content": { "application/json": { "schema": { "type": "string", "example": "Successfully Deleted API Key" } } } }, "400": { "description": "Bad Request - API key ID not provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "API Key ID not provided." } } } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - API key belongs to a different user", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "You do not have permission to delete this API Key." } } } } } }, "404": { "description": "Not Found - API key does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "API Key not found." } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=2.0" } } } } } } }, "tags": [ "Accounts" ] }, "get": { "summary": "show api key", "description": "Retrieves an existing API key belonging to the authenticated user.\n\nCLI Usage: vastai show api-key ID", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the API key to retrieve", "schema": { "type": "integer", "minimum": 1 }, "example": 123 } ], "responses": { "200": { "description": "API key successfully retrieved", "content": { "application/json": { "schema": { "type": "string", "example": "your-api-key-value" } } } }, "401": { "description": "Unauthorized - Invalid or missing authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - API key belongs to a different user", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "You do not have permission to access this key." } } } } } }, "404": { "description": "Not Found - API key does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "API Key not found." } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=1.0" } } } } } } }, "tags": [ "Accounts" ] } }, "/api/v0/workergroups/{id}/": { "delete": { "summary": "delete workergroup", "description": "Deletes an existing workergroup.\n\nCLI Usage: vastai delete workergroup ", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the workergroup to delete", "schema": { "type": "integer", "example": 4242 } } ], "responses": { "200": { "description": "Workergroup deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "deleted_workers": { "type": "array", "description": "List of worker instances that were deleted", "items": { "type": "integer" }, "example": [ 1001, 1002 ] }, "failed_workers": { "type": "array", "description": "List of worker instances that failed to delete", "items": { "type": "integer" }, "example": [] }, "msg": { "type": "string", "description": "Additional information about the deletion", "example": "Deleted workergroup and 2 workers" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "Invalid autojob ID" } } } } } }, "404": { "description": "Workergroup not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "no_such_workergroup" }, "msg": { "type": "string", "example": "No workergroup by that id is available." }, "id": { "type": "integer", "example": 4242 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "msg": { "type": "string" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=3.0" } } } } } } }, "tags": [ "Serverless" ] }, "put": { "summary": "update workergroup", "description": "Updates the properties of an existing workergroup based on the provided parameters.\n\nCLI Usage: vastai update workergroup [OPTIONS]", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the workergroup to update.", "schema": { "type": "integer", "example": 4242 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "min_load": { "type": "number", "description": "Minimum load for the workergroup.", "example": 1.0 }, "target_util": { "type": "number", "description": "Target utilization for the workergroup.", "example": 0.9 }, "cold_mult": { "type": "number", "description": "Cold multiplier for the workergroup.", "example": 3.0 }, "test_workers": { "type": "integer", "description": "Number of test workers for performance estimation.", "default": 3, "example": 3 }, "template_hash": { "type": "string", "description": "Template hash for the workergroup.", "example": "abc123def456" }, "template_id": { "type": "integer", "description": "Template ID for the workergroup.", "example": 456 }, "search_params": { "type": "string", "description": "Search parameters for offers (JSON object or query string).", "default": "verified=true rentable=true rented=false", "example": "gpu_name=RTX_3090 rentable=true" }, "launch_args": { "type": "string", "description": "Launch arguments for creating instances.", "example": "--env VAR=value" }, "gpu_ram": { "type": "number", "description": "Estimated GPU RAM requirement.", "example": 24 }, "endpoint_name": { "type": "string", "description": "Deployment endpoint name.", "example": "vLLM-Qwen3-8B" }, "endpoint_id": { "type": "integer", "description": "Deployment endpoint ID.", "example": 123 } } } } } }, "responses": { "200": { "description": "Successfully updated the workergroup.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "Workgroup not found for user" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "msg": { "type": "string" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=2.0" } } } } } } }, "tags": [ "Serverless" ] } }, "/api/v0/endptjobs/{id}/": { "delete": { "summary": "delete endpoint", "description": "Deletes an endpoint group by ID. Associated workergroups will also be deleted.\n\nCLI Usage: vastai delete endpoint ", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the endpoint group to delete", "schema": { "type": "integer", "example": 4242 } } ], "responses": { "200": { "description": "Endpoint group successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "deleted_workers": { "type": "array", "description": "List of worker instances that were deleted (if any)", "items": { "type": "integer" }, "example": [ 1001, 1002 ] }, "failed_workers": { "type": "array", "description": "List of worker instances that failed to delete (if any)", "items": { "type": "integer" }, "example": [] }, "msg": { "type": "string", "description": "Additional information about the deletion", "example": "Deleted endpoint job and 2 workers" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "Routegroup not found for user" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "msg": { "type": "string" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=3.0" } } } } } } }, "tags": [ "Serverless" ] }, "put": { "summary": "update endpoint", "description": "Updates the specified endpoint group with the provided parameters.\n\nCLI Usage: vastai update endpoint ID [OPTIONS]", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the endpoint group to update", "schema": { "type": "integer", "example": 4242 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "min_load": { "type": "number", "description": "Minimum floor load in perf units/s (token/s for LLMs)", "example": 0.0 }, "target_util": { "type": "number", "description": "Target capacity utilization (fraction, max 1.0)", "example": 0.9 }, "cold_mult": { "type": "number", "description": "Cold/stopped instance capacity target as multiple of hot capacity target", "example": 2.5 }, "cold_workers": { "type": "integer", "description": "Min number of workers to keep 'cold' when you have no load", "example": 5 }, "max_workers": { "type": "integer", "description": "Max number of workers your endpoint group can have", "example": 20 }, "endpoint_name": { "type": "string", "description": "Deployment endpoint name", "example": "my_endpoint" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "Endpointgroup not found for user" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "msg": { "type": "string" } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=2.0" } } } } } } }, "tags": [ "Serverless" ] } }, "/api/v0/ssh/{id}/": { "delete": { "summary": "delete ssh key", "description": "Removes an SSH key from the authenticated user's account\nCLI Usage: vastai delete ssh-key `", "operationId": "deleteSshKey", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the SSH key to delete", "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "SSH key successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] }, "example": { "success": true } } } }, "400": { "description": "Invalid request or SSH key not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "no_ssh_key" }, "msg": { "type": "string", "example": "No ssh key provided" } }, "required": [ "success", "error", "msg" ] }, "examples": { "not_found": { "value": { "success": false, "error": "no_ssh_key", "msg": "No ssh key provided" } }, "invalid": { "value": { "success": false, "error": "invalid_request", "msg": "Invalid request parameters" } } } } } } }, "tags": [ "Accounts" ] }, "put": { "summary": "update ssh key", "description": "Updates the specified SSH key with the provided value.\n\nCLI Usage: vastai update ssh-key id ssh_key", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the SSH key to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ssh_key" ], "properties": { "ssh_key": { "type": "string", "description": "The new value for the SSH key", "example": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC3..." } } } } } }, "responses": { "200": { "description": "SSH key updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "key": { "type": "object", "description": "The updated SSH key data" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=1.0" } } } } } } }, "tags": [ "Accounts" ] } }, "/api/v0/volumes": { "delete": { "summary": "delete volume", "description": "Delete a volume by its ID. CLI Usage: vastai delete volume VOLUME_ID", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "description": "ID of the volume to delete", "example": 100 } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "enum": [ "invalid_args" ] }, "msg": { "type": "string", "example": "Please provide a valid volume ID." } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "enum": [ "no_such_volume" ] }, "msg": { "type": "string", "example": "Volume with that ID does not exist." } } } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "API requests too frequent endpoint threshold=5.5" } } } } } } }, "tags": [ "Volumes" ] } }, "/api/v0/instances/{id}/": { "delete": { "summary": "destroy instance", "description": "Destroys/deletes an instance permanently. This is irreversible and will delete all data.\n\nCLI Usage: vast-ai destroy instance \nExample: vast-ai destroy instance 4242", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "integer" }, "description": "ID of the instance to destroy", "example": 4242 } ], "responses": { "200": { "description": "Instance destroyed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the destruction was successful" }, "msg": { "type": "string", "description": "Optional status message", "example": "Instance destroyed successfully" } } } } } }, "400": { "description": "Bad request - invalid instance ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "invalid instance_id" } } } } } }, "404": { "description": "Instance not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "not_found" }, "msg": { "type": "string", "example": "Instance not found" } } } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "rate_limit_exceeded" }, "msg": { "type": "string", "example": "API requests too frequent endpoint threshold=3.0" } } } } } } }, "security": [ { "BearerAuth": [] } ], "tags": [ "Instances" ] }, "put": { "summary": "manage instance", "description": "Manage instance state and labels. The operation is determined by the request body parameters.\n\nCLI Usage:\n- To stop: vastai stop instance \n- To start: vastai start instance \n- To label: vastai label instance