{ "openapi": "3.1.0", "info": { "title": "Vast.ai API", "description": "Welcome to Vast.ai 's API documentation. Our API allows you to programmatically manage GPU instances, handle machine operations, and automate your AI/ML workflow. Whether you're running individual GPU instances or managing a fleet of machines, our API provides comprehensive control over all Vast.ai platform features.", "version": "1.0.0", "contact": { "name": "Vast.ai Support", "url": "https://discord.gg/vast" } }, "servers": [ { "url": "https://console.vast.ai", "description": "Production 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.\n\nCLI Usage: `vastai 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: `vastai attach ssh `", "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...", "minLength": 1 } } } } } }, "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" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "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).\n\nCLI Usage: `vastai cancel copy --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.\n\nCLI Usage: `vastai copy `", "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.\n\nCLI Usage: `vastai cancel maint `", "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.\n\nCLI Usage: `vastai cancel sync --dst_id `", "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.\n\nCLI Usage: `vastai cloud copy [options]`", "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.\n\nCLI Usage: `vastai change bid --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, "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: `vastai cleanup machine `", "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 }, "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: `vastai create api-key --name --permission_file [--key_params ]`", "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 }, "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: `vastai 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, "example": 1 }, "target_util": { "type": "number", "description": "Target GPU utilization", "default": 0.9, "example": 0.9 }, "cold_mult": { "type": "number", "description": "Cold start multiplier", "default": 3, "example": 3 }, "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 }, "target_util": { "type": "number", "example": 0.9 }, "cold_mult": { "type": "number", "example": 3 }, "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: `vastai create endpoint [options]`", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "min_load": { "type": "number", "description": "Minimum load for the endpoint.", "default": 10, "example": 50 }, "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 }, "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.\n\nCLI Usage: `vastai show endpoints`", "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 }, "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: `vastai create env-var `", "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: `vastai 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: `vastai update env-var `", "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.\n\n- Use the search offers endpoint to discover available machines.\n- If `template_id` is provided, those template defaults are either merged or overridden by parameters specified in the request body.\n\n**Template Precedence Rules:**\n- **Scalar fields** (image, disk, runtype, etc.): Request value overrides template value\n- **`env`**: Merged by key. Request values win on key conflicts\n- **`extra_filters`**: Merged by key. Request values win on key conflicts\n\nFor detailed template usage, see [Creating and Using Templates with API](/api-reference/creating-and-using-templates-with-api).\n\nCLI Usage: `vastai create instance [options]`", "security": [ { "BearerAuth": [] } ], "tags": [ "Instances" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "ID of the offer to accept (ask_id)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "default": "vastai/base-image:@vastai-automatic-tag", "description": "Docker image to use for the instance.\n" }, "template_hash_id": { "type": "string", "description": "Content-based hash ID of a template to use as base configuration. Template values are merged with or overridden by request parameters (see precedence rules in endpoint description). When using a template, the `image` field is optional as the template provides it.\n\nExample: `4e17788f74f075dd9aab7d0d4427968f`\n" }, "label": { "type": "string", "description": "Custom name for the instance" }, "disk": { "type": "number", "format": "float", "description": "Size of local disk partition (in GB)\n" }, "runtype": { "type": "string", "description": "Launch mode for the instance. If omitted, defaults to 'ssh' unless `args/args_str` is provided.\n", "enum": [ "ssh", "jupyter", "args", "ssh_proxy", "ssh_direct", "jupyter_proxy", "jupyter_direct" ] }, "target_state": { "type": "string", "description": "Desired initial state of the instance\n", "enum": [ "running", "stopped" ] }, "price": { "type": "number", "description": "Bid price per machine (in $/hour). Only for interruptible instances", "minimum": 0.001, "maximum": 128 }, "env": { "type": "string", "description": "Environment variables and port mappings in Docker flag format. When using a template, request `env` is merged with template `env` - existing keys are retained, new keys are appended, conflicting keys use the request value.\n\nExample: `\"-e HF_TOKEN=hf_xxx123456789 -e MODEL_ID=TheBloke/Llama-2-7B-Chat-GPTQ -p 8000:8000\"`\n" }, "cancel_unavail": { "type": "boolean", "description": "Whether to cancel if instance cannot start immediately. Defaults to false for interruptibles. Defaults to true for on-demand with target_state='running'" }, "vm": { "type": "boolean", "description": "Whether this is a VM instance" }, "onstart": { "type": "string", "description": "Commands to run when instance starts\n\nExample : `env | grep _ >> /etc/environment; echo 'starting up'` \n" }, "args": { "type": "array", "items": { "type": "string" }, "description": "Arguments array to passed to the image entrypoint\n\nExample : `[\"bash\", \"-c\", \"env | grep _ >> /etc/environment; echo 'starting up'\"]`\n" }, "args_str": { "type": "string", "description": "Arguments string to pass to the entrypoint (alternative to args)\n\nExample : `args_str: bash -c \"env | grep _ >> /etc/environment; echo 'starting up'\"`\n" }, "use_jupyter_lab": { "type": "boolean", "description": "Launch instance with jupyter lab instead of notebook" }, "jupyter_dir": { "type": "string", "description": "Directory to launch Jupyter from\n\nExample : `/home/notebooks`\n" }, "python_utf8": { "type": "boolean", "description": "Set python's locale to C.UTF-8" }, "lang_utf8": { "type": "boolean", "description": "Set locale to C.UTF-8" }, "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)" }, "image_login": { "type": "string", "description": "Docker registry credentials if needed" }, "volume_info": { "type": "object", "description": "Volume creation/linking information", "properties": { "create_new": { "type": "boolean", "description": "Set to `true` to create a new volume, `false` to link an existing volume" }, "volume_id": { "type": "integer", "description": "If `create_new` is false: existing volume ID (from `show volumes`). If `create_new` is true: volume offer ID (from `search volumes`)\n" }, "size": { "type": "integer", "description": "Size of the volume in GB. Only used when `create_new` is true" }, "mount_path": { "type": "string", "description": "Mount path for the volume inside the container (e.g., `/workspace`)" } } } } }, "example": { "image": "vastai/base-image:@vastai-automatic-tag" } } } }, "responses": { "200": { "description": "Instance created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "If the instance was created successfully", "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" } } } } } } } } }, "/api/v0/network_volume/": { "put": { "summary": "create network-volume", "description": "Creates a network volume from an offer.\n\nCLI Usage: `vastai create network-volume [--name ]`", "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.\n\nCLI Usage: `vastai 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: `vastai create ssh-key `", "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.\n\nCLI Usage: `vastai show ssh-keys`", "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. Subaccounts can be restricted to host-only functionality.\n\nCLI Usage: `vastai create subaccount --email --username --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" }, "key_id": { "type": "integer", "description": "API key for the new account" } }, "example": { "id": 12345, "username": "testuser", "email": "user@example.com", "key_id": 67890 } } } } }, "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: `vastai set user --file `", "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](https://docs.vast.ai/documentation/teams/teams-overview) with given name and following default roles:\n- **Owner**: Full access to all team resources, settings, and member management. The team owner is the user who creates the team.\n- **Manager**: All permissions of owner except team deletion.\n- **Member**: Can view, create, and interact with instances, but cannot access billing, team management, autoscaler, or machines.\n\n- The API key used to create the team becomes the team key and is used for all team operations (e.g., creating roles, deleting the team).\n- You can optionally transfer credits from your personal account to the new team account using the `transfer_credit` field.\n\nCLI Usage: `vastai create team --team_name [--transfer_credit ]`", "security": [ { "BearerAuth": [] } ], "tags": [ "Team" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "team_name", "permissions" ], "properties": { "team_name": { "type": "string", "example": "my-awesome-team" }, "transfer_credit": { "type": "number", "format": "float", "description": "Credits to transfer from personal account to team", "example": 0 } } } } } }, "responses": { "200": { "description": "Team Successfully Created!", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "msg": { "type": "string", "example": "Team Successfully Created!" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "msg": { "type": "string", "example": "Team name already exists" } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "example": "auth_error" }, "msg": { "type": "string", "example": "Invalid user key" } } } } } } } }, "delete": { "summary": "destroy team", "description": "Deletes a team and all associated data including API keys, rights, invitations, memberships and metadata. The team owner's master API key is converted to a normal client key.\n\nCLI Usage: `vastai destroy team`", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Team successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "msg": { "type": "string", "example": "Team Successfully Deleted!" }, "pkey_id": { "type": "integer", "description": "ID of the user's team API key which was converted back to a client key.", "example": 12345 } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "auth_error", "msg": "Invalid user key" } } } }, "403": { "description": "Forbidden - Only the Team's Owner may delete the team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "not_allowed", "msg": "Only the Team's Owner may delete the team" } } } }, "404": { "description": "Not Found - Team does not exist or user is not a team account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_a_team": { "summary": "User is not a team account", "value": { "success": false, "error": "not_found", "msg": "Cannot Delete Team. User is not a team account" } }, "owner_not_found": { "summary": "Team owner not found", "value": { "success": false, "error": "not_found", "msg": "Team owner not found" } } } } } } }, "tags": [ "Team" ] } }, "/api/v0/team/roles/": { "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: `vastai 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", "properties": { "api": { "type": "object", "description": "API permissions", "allOf": [ { "title": "User Read", "type": "object", "properties": { "user_read": { "type": "object", "description": "Permission to read user info", "default": {} }, "instance_write": { "type": "object", "description": "Permission to write instances", "default": {} } } } ] } } } } } } } }, "responses": { "200": { "description": "Role created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "msg": { "type": "string", "example": "success" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "msg": { "type": "string", "example": "Missing permissions parameter" } } } } } }, "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.\n\nTemplates store default configuration values that can be used when creating instances. When an instance is created with a template reference, template values serve as defaults that can be overridden by request parameters.\n\nFor detailed usage, see [Creating and Using Templates with API](/api-reference/creating-and-using-templates-with-api).\n\nCLI Usage: `vastai create template --name --image [options]`", "tags": [ "Templates" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "image" ], "properties": { "name": { "type": "string", "default": "Example Template", "description": "Name of the template" }, "image": { "type": "string", "default": "vastai/base-image", "description": "Docker image path. Used when launching instances from this template." }, "tag": { "type": "string", "default": "latest", "description": "Docker image tag specifying version of the image. Defaults to `latest`. Can also be included in the `image` field instead.\n" }, "env": { "type": "string", "description": "Environment variables and port mappings in Docker flag format.\n\nExample: `\"-e HF_TOKEN=hf_xxx123456789 -e MODEL_ID=TheBloke/Llama-2-7B-Chat-GPTQ -p 8000:8000\"`\n" }, "onstart": { "type": "string", "description": "Commands to run when instance starts\n\nExample : `env | grep _ >> /etc/environment; echo 'starting up'` \n" }, "runtype": { "type": "string", "enum": [ "ssh", "jupyter", "args" ], "default": "args", "description": "Launch mode for the instance. Defaults to `args`. Recommended - use `ssh` with `ssh_direct: true` for reliable SSH access.\n" }, "ssh_direct": { "type": "boolean", "description": "Enable direct SSH connection" }, "jup_direct": { "type": "boolean", "description": "Enable direct Jupyter connection" }, "jupyter_dir": { "type": "string", "description": "Directory to launch Jupyter from\n\nExample : `/home/notebooks`\n" }, "use_jupyter_lab": { "type": "boolean", "description": "Use JupyterLab instead of Jupyter Notebook" }, "docker_login_repo": { "type": "string", "description": "Name of the private Docker repo (i.e docker.io)" }, "docker_login_user": { "type": "string", "description": "Username for private Docker repo" }, "docker_login_pass": { "type": "string", "description": "Access token or password for private Docker repo." }, "extra_filters": { "type": "object", "description": "Additional machine search filters. Example: `{\"cuda_max_good\": {\"gte\": 12.6}}`\n" }, "recommended_disk_space": { "type": "number", "description": "Recommended disk space in GB. Defaults to 8GB if not specified." }, "desc": { "type": "string", "description": "Short description of the template" }, "readme": { "type": "string", "description": "Longer documentation/readme content for the template" }, "args_str": { "type": "string", "description": "Arguments string passed to the container entrypoint when runtype is `args`" }, "use_ssh": { "type": "boolean", "description": "Enable SSH access to instances created from this template" }, "href": { "type": "string", "description": "Link to Docker Hub or image documentation" }, "repo": { "type": "string", "description": "Repository identifier (e.g., `library/ubuntu`)" }, "private": { "type": "boolean", "description": "Whether the template is private (not publicly searchable)" }, "volume_info": { "type": "object", "nullable": true, "description": "UI hint for volume configuration. Note: This does not affect instance creation - use `volume_info` in the instance creation request to actually attach volumes.\n" }, "hash_id": { "type": "string", "description": "Content-based hash ID of the template. Can be included when editing but will change based on new content." } } }, "example": { "name": "Example Template", "image": "vastai/base-image", "tag": "latest", "env": "-e MY_VAR=value -p 8000:8000", "runtype": "ssh", "ssh_direct": true } } } }, "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", "example": "Template Created Successfully! New Template ID: 123456" }, "template": { "type": "object", "description": "Template details", "properties": { "name": { "type": "string", "description": "Template name" }, "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 }, "error": { "type": "string", "example": "invalid_args" }, "msg": { "type": "string", "example": "Template name is required" } } } } } }, "401": { "description": "Unauthorized - invalid or missing API key" }, "429": { "description": "Rate limit exceeded" } } }, "delete": { "summary": "delete template", "description": "Deletes an existing template.\n\nPass the template's numeric `id` (not `hash_id`) in the request body.\n\nFor detailed usage, see [Creating and Using Templates with API](/api-reference/creating-and-using-templates-with-api).\n\nCLI Usage: `vastai delete template --template-id `", "tags": [ "Templates" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template_id" ], "properties": { "template_id": { "type": "integer", "description": "Numeric ID of the template to delete (not hash_id)" } } }, "example": { "template_id": 334548 } } } }, "responses": { "200": { "description": "Template deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "401": { "description": "Unauthorized - invalid or missing API key" }, "404": { "description": "Template not found" } } }, "put": { "summary": "edit template", "description": "Edits an existing template in place.\n\nTemplates are mutable. Use PUT with the template's `hash_id` to update it. You only need to include the fields you want to change - unchanged fields retain their existing values.\n\nNote: The template's `hash_id` will change after editing (since it's content-based), but the numeric `id` stays the same.\n\nFor detailed usage, see [Creating and Using Templates with API](/api-reference/creating-and-using-templates-with-api).\n\nCLI Usage: `vastai update template [options]`", "tags": [ "Templates" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hash_id" ], "properties": { "hash_id": { "type": "string", "description": "Hash ID of the template to edit. Required for identifying which template to update." }, "name": { "type": "string", "description": "Name of the template" }, "image": { "type": "string", "description": "Docker image path" }, "desc": { "type": "string", "description": "Short description of the template" }, "recommended_disk_space": { "type": "number", "description": "Recommended disk space in GB" } }, "additionalProperties": true }, "example": { "hash_id": "5915f1dc1ce881defb572015eb9d8178", "desc": "Updated description", "recommended_disk_space": 16 } } } }, "responses": { "200": { "description": "Template updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "template": { "type": "object", "properties": { "id": { "type": "integer", "description": "Template numeric ID (unchanged after edit)" }, "hash_id": { "type": "string", "description": "Updated template hash ID (changes based on content)" } } } } } } } }, "401": { "description": "Unauthorized - invalid or missing API key" }, "404": { "description": "Template not found" } } }, "get": { "summary": "search templates", "description": "Searches for templates using filter-based queries.\n\nUse `select_filters` to search by specific field conditions. Results include both your own templates and publicly shared templates.\n\n**Available filter fields:** `creator_id`, `created_at`, `count_created`, `default_tag`, `docker_login_repo`, `id`, `image`, `jup_direct`, `hash_id`, `name`, `recent_create_date`, `recommended_disk_space`, `recommended`, `ssh_direct`, `tag`, `use_ssh`\n\n**Operators:** `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `in`, `notin`\n\nFor detailed usage, see [Creating and Using Templates with API](/api-reference/creating-and-using-templates-with-api).\n\nCLI Usage: `vastai search templates`", "parameters": [ { "name": "select_filters", "in": "query", "required": false, "schema": { "type": "string" }, "description": "JSON-encoded filter object. Format: `{\"field\": {\"op\": value}}`. Example: `{\"use_ssh\": {\"eq\": true}, \"recommended\": {\"eq\": true}}` or `{\"count_created\": {\"gt\": 100}}`\n" }, { "name": "select_cols", "in": "query", "required": false, "schema": { "type": "string" }, "description": "JSON-encoded array of columns to return. Example: `[\"*\"]` for all columns or `[\"id\", \"name\", \"hash_id\"]` for specific columns.\n" }, { "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 `", "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" ] } }, "/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" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" }, "msg": { "type": "string" } } } } } }, "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 } } } } } }, "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 }, "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 }, "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 [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 }, "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\n\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 `", "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.\n\nCLI Usage: `vastai delete volume `", "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" ] }, "put": { "summary": "rent volume", "description": "Rent/create a new volume with specified parameters.\n\nCLI Usage: `vastai create volume --size `", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "description": "ID for the volume", "example": 420 }, "size": { "type": "integer", "description": "Size in GB (Defaults to 15)", "example": 15 } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "volume_name": { "type": "string", "description": "Name of the created/resized volume", "example": "V.20118481" } } } } } } }, "tags": [ "Volumes" ] }, "get": { "summary": "list volumes", "description": "Retrieve information about all volumes rented by you.\n\nCLI Usage: `vastai show volumes`", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "type": "object", "properties": { "volumes": { "type": "array", "items": { "$ref": "#/components/schemas/Volume" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Authentication credentials were not provided." } } } } } }, "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: `vastai destroy instance `", "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