From 259b15669bce9e079cef97e0e7a0eba8c2c91cd0 Mon Sep 17 00:00:00 2001 From: "guthrie@vast.ai" Date: Thu, 2 Apr 2026 18:53:49 -0700 Subject: [PATCH 1/8] Add CLI/SDK/API reference docs and update navigation - Add full CLI reference (138 command pages + get-started, auth, permissions, templates, rate-limits) - Add full Python SDK reference (138 method pages + serverless client docs + get-started pages) - Add API reference authentication and permissions pages - Add warning to API reference introduction page - Update docs.json: replace SDK/CLI/API tabs with structured reference navigation - Add redirects for /cli/commands, /api-reference/permissions-and-authorization - Remove stale cli/commands.mdx (replaced by /cli/reference/) Co-Authored-By: Claude Sonnet 4.6 --- api-reference/authentication.mdx | 97 + api-reference/introduction.mdx | 183 +- api-reference/permissions.mdx | 238 ++ cli/authentication.mdx | 103 + cli/commands.mdx | 2097 ----------------- cli/hello-world.mdx | 212 ++ cli/permissions.mdx | 222 ++ cli/rate-limits.mdx | 84 + cli/reference/add-network-disk.mdx | 56 + cli/reference/attach-ssh.mdx | 48 + cli/reference/cancel-copy.mdx | 42 + cli/reference/cancel-maint.mdx | 44 + cli/reference/cancel-sync.mdx | 42 + cli/reference/change-bid.mdx | 67 + cli/reference/cleanup-machine.mdx | 46 + cli/reference/clone-volume.mdx | 55 + cli/reference/cloud-copy.mdx | 106 + cli/reference/copy.mdx | 75 + cli/reference/create-api-key.mdx | 49 + cli/reference/create-cluster.mdx | 44 + cli/reference/create-endpoint.mdx | 78 + cli/reference/create-env-var.mdx | 40 + cli/reference/create-instance.mdx | 170 ++ cli/reference/create-network-volume.mdx | 51 + cli/reference/create-overlay.mdx | 44 + cli/reference/create-ssh-key.mdx | 59 + cli/reference/create-subaccount.mdx | 56 + cli/reference/create-team-role.mdx | 45 + cli/reference/create-team.mdx | 64 + cli/reference/create-template.mdx | 120 + cli/reference/create-volume.mdx | 51 + cli/reference/create-workergroup.mdx | 90 + cli/reference/defrag-machines.mdx | 43 + cli/reference/delete-api-key.mdx | 36 + cli/reference/delete-cluster.mdx | 40 + cli/reference/delete-deployment.mdx | 53 + cli/reference/delete-endpoint.mdx | 40 + cli/reference/delete-env-var.mdx | 36 + cli/reference/delete-machine.mdx | 39 + cli/reference/delete-overlay.mdx | 36 + cli/reference/delete-scheduled-job.mdx | 36 + cli/reference/delete-ssh-key.mdx | 36 + cli/reference/delete-template.mdx | 46 + cli/reference/delete-volume.mdx | 40 + cli/reference/delete-workergroup.mdx | 41 + cli/reference/destroy-instance.mdx | 41 + cli/reference/destroy-instances.mdx | 36 + cli/reference/destroy-team.mdx | 30 + cli/reference/detach-ssh.mdx | 44 + cli/reference/execute.mdx | 77 + cli/reference/get-endpt-logs.mdx | 50 + cli/reference/get-wrkgrp-logs.mdx | 50 + cli/reference/invite-member.mdx | 40 + cli/reference/join-cluster.mdx | 44 + cli/reference/join-overlay.mdx | 44 + cli/reference/label-instance.mdx | 40 + cli/reference/launch-instance.mdx | 155 ++ cli/reference/list-machine.mdx | 93 + cli/reference/list-machines.mdx | 91 + cli/reference/list-network-volume.mdx | 53 + cli/reference/list-volume.mdx | 57 + cli/reference/list-volumes.mdx | 57 + cli/reference/logs.mdx | 50 + cli/reference/prepay-instance.mdx | 40 + cli/reference/reboot-instance.mdx | 62 + cli/reference/recycle-instance.mdx | 40 + cli/reference/remove-defjob.mdx | 39 + cli/reference/remove-machine-from-cluster.mdx | 49 + cli/reference/remove-member.mdx | 36 + cli/reference/remove-team-role.mdx | 36 + cli/reference/reports.mdx | 36 + cli/reference/reset-api-key.mdx | 30 + cli/reference/schedule-maint.mdx | 61 + cli/reference/scp-url.mdx | 36 + cli/reference/search-benchmarks.mdx | 65 + cli/reference/search-instances.mdx | 165 ++ cli/reference/search-invoices.mdx | 81 + cli/reference/search-network-volumes.mdx | 81 + cli/reference/search-offers.mdx | 165 ++ cli/reference/search-templates.mdx | 72 + cli/reference/search-volumes.mdx | 97 + cli/reference/self-test-machine.mdx | 57 + cli/reference/set-api-key.mdx | 36 + cli/reference/set-defjob.mdx | 65 + cli/reference/set-min-bid.mdx | 49 + cli/reference/set-user.mdx | 60 + cli/reference/show-api-key.mdx | 36 + cli/reference/show-api-keys.mdx | 30 + cli/reference/show-audit-logs.mdx | 30 + cli/reference/show-clusters.mdx | 34 + cli/reference/show-connections.mdx | 30 + cli/reference/show-deployment-versions.mdx | 40 + cli/reference/show-deployment.mdx | 40 + cli/reference/show-deployments.mdx | 34 + cli/reference/show-deposit.mdx | 36 + cli/reference/show-earnings.mdx | 48 + cli/reference/show-endpoints.mdx | 34 + cli/reference/show-env-vars.mdx | 36 + cli/reference/show-instance.mdx | 36 + cli/reference/show-instances-v1.mdx | 94 + cli/reference/show-instances.mdx | 36 + cli/reference/show-invoices-v1.mdx | 96 + cli/reference/show-invoices.mdx | 56 + cli/reference/show-ipaddrs.mdx | 30 + cli/reference/show-machine.mdx | 45 + cli/reference/show-machines.mdx | 39 + cli/reference/show-maints.mdx | 44 + cli/reference/show-members.mdx | 30 + cli/reference/show-network-disks.mdx | 37 + cli/reference/show-overlays.mdx | 34 + cli/reference/show-scheduled-jobs.mdx | 30 + cli/reference/show-ssh-keys.mdx | 30 + cli/reference/show-subaccounts.mdx | 36 + cli/reference/show-team-role.mdx | 36 + cli/reference/show-team-roles.mdx | 30 + cli/reference/show-user.mdx | 40 + cli/reference/show-volumes.mdx | 40 + cli/reference/show-workergroups.mdx | 34 + cli/reference/ssh-url.mdx | 36 + cli/reference/start-instance.mdx | 42 + cli/reference/start-instances.mdx | 36 + cli/reference/stop-instance.mdx | 42 + cli/reference/stop-instances.mdx | 42 + cli/reference/take-snapshot.mdx | 66 + cli/reference/tfa-activate.mdx | 77 + cli/reference/tfa-auth-new.mdx | 77 + cli/reference/tfa-delete.mdx | 85 + cli/reference/tfa-login.mdx | 64 + cli/reference/tfa-regen-codes.mdx | 74 + cli/reference/tfa-resend-sms.mdx | 51 + cli/reference/tfa-send-email.mdx | 36 + cli/reference/tfa-send-sms.mdx | 44 + cli/reference/tfa-status.mdx | 37 + cli/reference/tfa-totp-setup.mdx | 55 + cli/reference/tfa-update.mdx | 57 + cli/reference/transfer-credit.mdx | 50 + cli/reference/unlist-machine.mdx | 39 + cli/reference/unlist-network-volume.mdx | 39 + cli/reference/unlist-volume.mdx | 39 + cli/reference/update-endpoint.mdx | 86 + cli/reference/update-env-var.mdx | 40 + cli/reference/update-instance.mdx | 66 + cli/reference/update-ssh-key.mdx | 40 + cli/reference/update-team-role.mdx | 46 + cli/reference/update-template.mdx | 126 + cli/reference/update-workergroup.mdx | 94 + cli/reference/update-workers.mdx | 50 + cli/templates.mdx | 289 +++ docs.json | 500 +++- sdk/python/authentication.mdx | 128 + sdk/python/hello-world.mdx | 292 +++ sdk/python/permissions.mdx | 255 ++ sdk/python/quickstart.mdx | 383 ++- sdk/python/rate-limits.mdx | 112 + sdk/python/reference/add-network-disk.mdx | 40 + sdk/python/reference/attach-ssh.mdx | 36 + sdk/python/reference/cancel-copy.mdx | 32 + sdk/python/reference/cancel-maint.mdx | 34 + sdk/python/reference/cancel-sync.mdx | 32 + sdk/python/reference/change-bid.mdx | 36 + sdk/python/reference/cleanup-machine.mdx | 34 + sdk/python/reference/clone-volume.mdx | 49 + sdk/python/reference/cloud-copy.mdx | 54 + sdk/python/reference/copy.mdx | 40 + sdk/python/reference/create-api-key.mdx | 40 + sdk/python/reference/create-cluster.mdx | 36 + sdk/python/reference/create-endpoint.mdx | 59 + sdk/python/reference/create-env-var.mdx | 36 + sdk/python/reference/create-instance.mdx | 139 ++ sdk/python/reference/create-instances.mdx | 169 ++ .../reference/create-network-volume.mdx | 40 + sdk/python/reference/create-overlay.mdx | 36 + sdk/python/reference/create-ssh-key.mdx | 32 + sdk/python/reference/create-subaccount.mdx | 49 + sdk/python/reference/create-team-role.mdx | 36 + sdk/python/reference/create-team.mdx | 32 + sdk/python/reference/create-template.mdx | 94 + sdk/python/reference/create-volume.mdx | 40 + sdk/python/reference/create-workergroup.mdx | 94 + sdk/python/reference/defrag-machines.mdx | 34 + sdk/python/reference/delete-api-key.mdx | 32 + sdk/python/reference/delete-cluster.mdx | 32 + sdk/python/reference/delete-deployment.mdx | 40 + sdk/python/reference/delete-endpoint.mdx | 32 + sdk/python/reference/delete-env-var.mdx | 32 + sdk/python/reference/delete-machine.mdx | 34 + sdk/python/reference/delete-overlay.mdx | 32 + sdk/python/reference/delete-scheduled-job.mdx | 32 + sdk/python/reference/delete-ssh-key.mdx | 32 + sdk/python/reference/delete-template.mdx | 36 + sdk/python/reference/delete-volume.mdx | 32 + sdk/python/reference/delete-workergroup.mdx | 32 + sdk/python/reference/destroy-instance.mdx | 32 + sdk/python/reference/destroy-instances.mdx | 32 + sdk/python/reference/destroy-team.mdx | 26 + sdk/python/reference/detach-ssh.mdx | 36 + sdk/python/reference/execute.mdx | 36 + .../reference/generate-pdf-invoices.mdx | 54 + sdk/python/reference/get-endpt-logs.mdx | 40 + sdk/python/reference/get-wrkgrp-logs.mdx | 40 + sdk/python/reference/invite-member.mdx | 36 + sdk/python/reference/join-cluster.mdx | 36 + sdk/python/reference/join-overlay.mdx | 36 + sdk/python/reference/label-instance.mdx | 36 + sdk/python/reference/launch-instance.mdx | 166 ++ sdk/python/reference/list-machine.mdx | 71 + sdk/python/reference/list-machines.mdx | 71 + sdk/python/reference/list-network-volume.mdx | 49 + sdk/python/reference/list-volume.mdx | 49 + sdk/python/reference/list-volumes.mdx | 49 + sdk/python/reference/logs.mdx | 36 + sdk/python/reference/prepay-instance.mdx | 36 + sdk/python/reference/reboot-instance.mdx | 32 + sdk/python/reference/recycle-instance.mdx | 32 + sdk/python/reference/remove-defjob.mdx | 34 + .../reference/remove-machine-from-cluster.mdx | 40 + sdk/python/reference/remove-member.mdx | 32 + sdk/python/reference/remove-team-role.mdx | 32 + sdk/python/reference/reports.mdx | 32 + sdk/python/reference/reset-api-key.mdx | 26 + sdk/python/reference/schedule-maint.mdx | 42 + sdk/python/reference/scp-url.mdx | 32 + sdk/python/reference/search-benchmarks.mdx | 32 + sdk/python/reference/search-invoices.mdx | 32 + .../reference/search-network-volumes.mdx | 54 + sdk/python/reference/search-offers.mdx | 69 + sdk/python/reference/search-templates.mdx | 32 + sdk/python/reference/search-volumes.mdx | 40 + sdk/python/reference/self-test-machine.mdx | 66 + sdk/python/reference/set-api-key.mdx | 32 + sdk/python/reference/set-defjob.mdx | 61 + sdk/python/reference/set-min-bid.mdx | 38 + sdk/python/reference/set-user.mdx | 32 + sdk/python/reference/show-api-key.mdx | 32 + sdk/python/reference/show-api-keys.mdx | 26 + sdk/python/reference/show-audit-logs.mdx | 26 + sdk/python/reference/show-clusters.mdx | 26 + sdk/python/reference/show-connections.mdx | 26 + .../reference/show-deployment-versions.mdx | 32 + sdk/python/reference/show-deployment.mdx | 32 + sdk/python/reference/show-deployments.mdx | 26 + sdk/python/reference/show-deposit.mdx | 32 + sdk/python/reference/show-earnings.mdx | 49 + sdk/python/reference/show-endpoints.mdx | 26 + sdk/python/reference/show-env-vars.mdx | 32 + sdk/python/reference/show-instance.mdx | 32 + sdk/python/reference/show-instances-v1.mdx | 84 + sdk/python/reference/show-instances.mdx | 32 + sdk/python/reference/show-invoices-v1.mdx | 84 + sdk/python/reference/show-invoices.mdx | 59 + sdk/python/reference/show-ipaddrs.mdx | 26 + sdk/python/reference/show-machine.mdx | 38 + sdk/python/reference/show-machines.mdx | 38 + sdk/python/reference/show-maints.mdx | 38 + sdk/python/reference/show-members.mdx | 26 + sdk/python/reference/show-network-disks.mdx | 26 + sdk/python/reference/show-overlays.mdx | 26 + sdk/python/reference/show-scheduled-jobs.mdx | 26 + sdk/python/reference/show-ssh-keys.mdx | 26 + sdk/python/reference/show-subaccounts.mdx | 32 + sdk/python/reference/show-team-role.mdx | 32 + sdk/python/reference/show-team-roles.mdx | 26 + sdk/python/reference/show-user.mdx | 32 + sdk/python/reference/show-volumes.mdx | 32 + sdk/python/reference/show-workergroups.mdx | 26 + sdk/python/reference/ssh-url.mdx | 32 + sdk/python/reference/start-instance.mdx | 32 + sdk/python/reference/start-instances.mdx | 32 + sdk/python/reference/stop-instance.mdx | 32 + sdk/python/reference/stop-instances.mdx | 32 + sdk/python/reference/take-snapshot.mdx | 59 + sdk/python/reference/tfa-activate.mdx | 54 + sdk/python/reference/tfa-delete.mdx | 59 + sdk/python/reference/tfa-login.mdx | 54 + sdk/python/reference/tfa-regen-codes.mdx | 54 + sdk/python/reference/tfa-resend-sms.mdx | 36 + sdk/python/reference/tfa-send-sms.mdx | 32 + sdk/python/reference/tfa-status.mdx | 26 + sdk/python/reference/tfa-totp-setup.mdx | 26 + sdk/python/reference/tfa-update.mdx | 40 + sdk/python/reference/transfer-credit.mdx | 36 + sdk/python/reference/unlist-machine.mdx | 34 + .../reference/unlist-network-volume.mdx | 32 + sdk/python/reference/unlist-volume.mdx | 32 + sdk/python/reference/update-endpoint.mdx | 64 + sdk/python/reference/update-env-var.mdx | 36 + sdk/python/reference/update-instance.mdx | 64 + sdk/python/reference/update-ssh-key.mdx | 36 + sdk/python/reference/update-team-role.mdx | 40 + sdk/python/reference/update-template.mdx | 79 + sdk/python/reference/update-workergroup.mdx | 99 + sdk/python/reference/update-workers.mdx | 36 + sdk/python/reference/vastai.mdx | 80 + sdk/python/serverless/benchmark-config.mdx | 34 + sdk/python/serverless/client-worker.mdx | 80 + sdk/python/serverless/endpoint.mdx | 162 ++ sdk/python/serverless/handler-config.mdx | 58 + sdk/python/serverless/log-action-config.mdx | 34 + sdk/python/serverless/server-worker.mdx | 38 + sdk/python/serverless/serverless-request.mdx | 24 + sdk/python/serverless/serverless.mdx | 238 ++ sdk/python/serverless/session.mdx | 113 + sdk/python/serverless/worker-config.mdx | 48 + sdk/python/templates.mdx | 382 +++ 304 files changed, 17476 insertions(+), 2335 deletions(-) create mode 100644 api-reference/authentication.mdx create mode 100644 api-reference/permissions.mdx create mode 100644 cli/authentication.mdx delete mode 100644 cli/commands.mdx create mode 100644 cli/hello-world.mdx create mode 100644 cli/permissions.mdx create mode 100644 cli/rate-limits.mdx create mode 100644 cli/reference/add-network-disk.mdx create mode 100644 cli/reference/attach-ssh.mdx create mode 100644 cli/reference/cancel-copy.mdx create mode 100644 cli/reference/cancel-maint.mdx create mode 100644 cli/reference/cancel-sync.mdx create mode 100644 cli/reference/change-bid.mdx create mode 100644 cli/reference/cleanup-machine.mdx create mode 100644 cli/reference/clone-volume.mdx create mode 100644 cli/reference/cloud-copy.mdx create mode 100644 cli/reference/copy.mdx create mode 100644 cli/reference/create-api-key.mdx create mode 100644 cli/reference/create-cluster.mdx create mode 100644 cli/reference/create-endpoint.mdx create mode 100644 cli/reference/create-env-var.mdx create mode 100644 cli/reference/create-instance.mdx create mode 100644 cli/reference/create-network-volume.mdx create mode 100644 cli/reference/create-overlay.mdx create mode 100644 cli/reference/create-ssh-key.mdx create mode 100644 cli/reference/create-subaccount.mdx create mode 100644 cli/reference/create-team-role.mdx create mode 100644 cli/reference/create-team.mdx create mode 100644 cli/reference/create-template.mdx create mode 100644 cli/reference/create-volume.mdx create mode 100644 cli/reference/create-workergroup.mdx create mode 100644 cli/reference/defrag-machines.mdx create mode 100644 cli/reference/delete-api-key.mdx create mode 100644 cli/reference/delete-cluster.mdx create mode 100644 cli/reference/delete-deployment.mdx create mode 100644 cli/reference/delete-endpoint.mdx create mode 100644 cli/reference/delete-env-var.mdx create mode 100644 cli/reference/delete-machine.mdx create mode 100644 cli/reference/delete-overlay.mdx create mode 100644 cli/reference/delete-scheduled-job.mdx create mode 100644 cli/reference/delete-ssh-key.mdx create mode 100644 cli/reference/delete-template.mdx create mode 100644 cli/reference/delete-volume.mdx create mode 100644 cli/reference/delete-workergroup.mdx create mode 100644 cli/reference/destroy-instance.mdx create mode 100644 cli/reference/destroy-instances.mdx create mode 100644 cli/reference/destroy-team.mdx create mode 100644 cli/reference/detach-ssh.mdx create mode 100644 cli/reference/execute.mdx create mode 100644 cli/reference/get-endpt-logs.mdx create mode 100644 cli/reference/get-wrkgrp-logs.mdx create mode 100644 cli/reference/invite-member.mdx create mode 100644 cli/reference/join-cluster.mdx create mode 100644 cli/reference/join-overlay.mdx create mode 100644 cli/reference/label-instance.mdx create mode 100644 cli/reference/launch-instance.mdx create mode 100644 cli/reference/list-machine.mdx create mode 100644 cli/reference/list-machines.mdx create mode 100644 cli/reference/list-network-volume.mdx create mode 100644 cli/reference/list-volume.mdx create mode 100644 cli/reference/list-volumes.mdx create mode 100644 cli/reference/logs.mdx create mode 100644 cli/reference/prepay-instance.mdx create mode 100644 cli/reference/reboot-instance.mdx create mode 100644 cli/reference/recycle-instance.mdx create mode 100644 cli/reference/remove-defjob.mdx create mode 100644 cli/reference/remove-machine-from-cluster.mdx create mode 100644 cli/reference/remove-member.mdx create mode 100644 cli/reference/remove-team-role.mdx create mode 100644 cli/reference/reports.mdx create mode 100644 cli/reference/reset-api-key.mdx create mode 100644 cli/reference/schedule-maint.mdx create mode 100644 cli/reference/scp-url.mdx create mode 100644 cli/reference/search-benchmarks.mdx create mode 100644 cli/reference/search-instances.mdx create mode 100644 cli/reference/search-invoices.mdx create mode 100644 cli/reference/search-network-volumes.mdx create mode 100644 cli/reference/search-offers.mdx create mode 100644 cli/reference/search-templates.mdx create mode 100644 cli/reference/search-volumes.mdx create mode 100644 cli/reference/self-test-machine.mdx create mode 100644 cli/reference/set-api-key.mdx create mode 100644 cli/reference/set-defjob.mdx create mode 100644 cli/reference/set-min-bid.mdx create mode 100644 cli/reference/set-user.mdx create mode 100644 cli/reference/show-api-key.mdx create mode 100644 cli/reference/show-api-keys.mdx create mode 100644 cli/reference/show-audit-logs.mdx create mode 100644 cli/reference/show-clusters.mdx create mode 100644 cli/reference/show-connections.mdx create mode 100644 cli/reference/show-deployment-versions.mdx create mode 100644 cli/reference/show-deployment.mdx create mode 100644 cli/reference/show-deployments.mdx create mode 100644 cli/reference/show-deposit.mdx create mode 100644 cli/reference/show-earnings.mdx create mode 100644 cli/reference/show-endpoints.mdx create mode 100644 cli/reference/show-env-vars.mdx create mode 100644 cli/reference/show-instance.mdx create mode 100644 cli/reference/show-instances-v1.mdx create mode 100644 cli/reference/show-instances.mdx create mode 100644 cli/reference/show-invoices-v1.mdx create mode 100644 cli/reference/show-invoices.mdx create mode 100644 cli/reference/show-ipaddrs.mdx create mode 100644 cli/reference/show-machine.mdx create mode 100644 cli/reference/show-machines.mdx create mode 100644 cli/reference/show-maints.mdx create mode 100644 cli/reference/show-members.mdx create mode 100644 cli/reference/show-network-disks.mdx create mode 100644 cli/reference/show-overlays.mdx create mode 100644 cli/reference/show-scheduled-jobs.mdx create mode 100644 cli/reference/show-ssh-keys.mdx create mode 100644 cli/reference/show-subaccounts.mdx create mode 100644 cli/reference/show-team-role.mdx create mode 100644 cli/reference/show-team-roles.mdx create mode 100644 cli/reference/show-user.mdx create mode 100644 cli/reference/show-volumes.mdx create mode 100644 cli/reference/show-workergroups.mdx create mode 100644 cli/reference/ssh-url.mdx create mode 100644 cli/reference/start-instance.mdx create mode 100644 cli/reference/start-instances.mdx create mode 100644 cli/reference/stop-instance.mdx create mode 100644 cli/reference/stop-instances.mdx create mode 100644 cli/reference/take-snapshot.mdx create mode 100644 cli/reference/tfa-activate.mdx create mode 100644 cli/reference/tfa-auth-new.mdx create mode 100644 cli/reference/tfa-delete.mdx create mode 100644 cli/reference/tfa-login.mdx create mode 100644 cli/reference/tfa-regen-codes.mdx create mode 100644 cli/reference/tfa-resend-sms.mdx create mode 100644 cli/reference/tfa-send-email.mdx create mode 100644 cli/reference/tfa-send-sms.mdx create mode 100644 cli/reference/tfa-status.mdx create mode 100644 cli/reference/tfa-totp-setup.mdx create mode 100644 cli/reference/tfa-update.mdx create mode 100644 cli/reference/transfer-credit.mdx create mode 100644 cli/reference/unlist-machine.mdx create mode 100644 cli/reference/unlist-network-volume.mdx create mode 100644 cli/reference/unlist-volume.mdx create mode 100644 cli/reference/update-endpoint.mdx create mode 100644 cli/reference/update-env-var.mdx create mode 100644 cli/reference/update-instance.mdx create mode 100644 cli/reference/update-ssh-key.mdx create mode 100644 cli/reference/update-team-role.mdx create mode 100644 cli/reference/update-template.mdx create mode 100644 cli/reference/update-workergroup.mdx create mode 100644 cli/reference/update-workers.mdx create mode 100644 cli/templates.mdx create mode 100644 sdk/python/authentication.mdx create mode 100644 sdk/python/hello-world.mdx create mode 100644 sdk/python/permissions.mdx create mode 100644 sdk/python/rate-limits.mdx create mode 100644 sdk/python/reference/add-network-disk.mdx create mode 100644 sdk/python/reference/attach-ssh.mdx create mode 100644 sdk/python/reference/cancel-copy.mdx create mode 100644 sdk/python/reference/cancel-maint.mdx create mode 100644 sdk/python/reference/cancel-sync.mdx create mode 100644 sdk/python/reference/change-bid.mdx create mode 100644 sdk/python/reference/cleanup-machine.mdx create mode 100644 sdk/python/reference/clone-volume.mdx create mode 100644 sdk/python/reference/cloud-copy.mdx create mode 100644 sdk/python/reference/copy.mdx create mode 100644 sdk/python/reference/create-api-key.mdx create mode 100644 sdk/python/reference/create-cluster.mdx create mode 100644 sdk/python/reference/create-endpoint.mdx create mode 100644 sdk/python/reference/create-env-var.mdx create mode 100644 sdk/python/reference/create-instance.mdx create mode 100644 sdk/python/reference/create-instances.mdx create mode 100644 sdk/python/reference/create-network-volume.mdx create mode 100644 sdk/python/reference/create-overlay.mdx create mode 100644 sdk/python/reference/create-ssh-key.mdx create mode 100644 sdk/python/reference/create-subaccount.mdx create mode 100644 sdk/python/reference/create-team-role.mdx create mode 100644 sdk/python/reference/create-team.mdx create mode 100644 sdk/python/reference/create-template.mdx create mode 100644 sdk/python/reference/create-volume.mdx create mode 100644 sdk/python/reference/create-workergroup.mdx create mode 100644 sdk/python/reference/defrag-machines.mdx create mode 100644 sdk/python/reference/delete-api-key.mdx create mode 100644 sdk/python/reference/delete-cluster.mdx create mode 100644 sdk/python/reference/delete-deployment.mdx create mode 100644 sdk/python/reference/delete-endpoint.mdx create mode 100644 sdk/python/reference/delete-env-var.mdx create mode 100644 sdk/python/reference/delete-machine.mdx create mode 100644 sdk/python/reference/delete-overlay.mdx create mode 100644 sdk/python/reference/delete-scheduled-job.mdx create mode 100644 sdk/python/reference/delete-ssh-key.mdx create mode 100644 sdk/python/reference/delete-template.mdx create mode 100644 sdk/python/reference/delete-volume.mdx create mode 100644 sdk/python/reference/delete-workergroup.mdx create mode 100644 sdk/python/reference/destroy-instance.mdx create mode 100644 sdk/python/reference/destroy-instances.mdx create mode 100644 sdk/python/reference/destroy-team.mdx create mode 100644 sdk/python/reference/detach-ssh.mdx create mode 100644 sdk/python/reference/execute.mdx create mode 100644 sdk/python/reference/generate-pdf-invoices.mdx create mode 100644 sdk/python/reference/get-endpt-logs.mdx create mode 100644 sdk/python/reference/get-wrkgrp-logs.mdx create mode 100644 sdk/python/reference/invite-member.mdx create mode 100644 sdk/python/reference/join-cluster.mdx create mode 100644 sdk/python/reference/join-overlay.mdx create mode 100644 sdk/python/reference/label-instance.mdx create mode 100644 sdk/python/reference/launch-instance.mdx create mode 100644 sdk/python/reference/list-machine.mdx create mode 100644 sdk/python/reference/list-machines.mdx create mode 100644 sdk/python/reference/list-network-volume.mdx create mode 100644 sdk/python/reference/list-volume.mdx create mode 100644 sdk/python/reference/list-volumes.mdx create mode 100644 sdk/python/reference/logs.mdx create mode 100644 sdk/python/reference/prepay-instance.mdx create mode 100644 sdk/python/reference/reboot-instance.mdx create mode 100644 sdk/python/reference/recycle-instance.mdx create mode 100644 sdk/python/reference/remove-defjob.mdx create mode 100644 sdk/python/reference/remove-machine-from-cluster.mdx create mode 100644 sdk/python/reference/remove-member.mdx create mode 100644 sdk/python/reference/remove-team-role.mdx create mode 100644 sdk/python/reference/reports.mdx create mode 100644 sdk/python/reference/reset-api-key.mdx create mode 100644 sdk/python/reference/schedule-maint.mdx create mode 100644 sdk/python/reference/scp-url.mdx create mode 100644 sdk/python/reference/search-benchmarks.mdx create mode 100644 sdk/python/reference/search-invoices.mdx create mode 100644 sdk/python/reference/search-network-volumes.mdx create mode 100644 sdk/python/reference/search-offers.mdx create mode 100644 sdk/python/reference/search-templates.mdx create mode 100644 sdk/python/reference/search-volumes.mdx create mode 100644 sdk/python/reference/self-test-machine.mdx create mode 100644 sdk/python/reference/set-api-key.mdx create mode 100644 sdk/python/reference/set-defjob.mdx create mode 100644 sdk/python/reference/set-min-bid.mdx create mode 100644 sdk/python/reference/set-user.mdx create mode 100644 sdk/python/reference/show-api-key.mdx create mode 100644 sdk/python/reference/show-api-keys.mdx create mode 100644 sdk/python/reference/show-audit-logs.mdx create mode 100644 sdk/python/reference/show-clusters.mdx create mode 100644 sdk/python/reference/show-connections.mdx create mode 100644 sdk/python/reference/show-deployment-versions.mdx create mode 100644 sdk/python/reference/show-deployment.mdx create mode 100644 sdk/python/reference/show-deployments.mdx create mode 100644 sdk/python/reference/show-deposit.mdx create mode 100644 sdk/python/reference/show-earnings.mdx create mode 100644 sdk/python/reference/show-endpoints.mdx create mode 100644 sdk/python/reference/show-env-vars.mdx create mode 100644 sdk/python/reference/show-instance.mdx create mode 100644 sdk/python/reference/show-instances-v1.mdx create mode 100644 sdk/python/reference/show-instances.mdx create mode 100644 sdk/python/reference/show-invoices-v1.mdx create mode 100644 sdk/python/reference/show-invoices.mdx create mode 100644 sdk/python/reference/show-ipaddrs.mdx create mode 100644 sdk/python/reference/show-machine.mdx create mode 100644 sdk/python/reference/show-machines.mdx create mode 100644 sdk/python/reference/show-maints.mdx create mode 100644 sdk/python/reference/show-members.mdx create mode 100644 sdk/python/reference/show-network-disks.mdx create mode 100644 sdk/python/reference/show-overlays.mdx create mode 100644 sdk/python/reference/show-scheduled-jobs.mdx create mode 100644 sdk/python/reference/show-ssh-keys.mdx create mode 100644 sdk/python/reference/show-subaccounts.mdx create mode 100644 sdk/python/reference/show-team-role.mdx create mode 100644 sdk/python/reference/show-team-roles.mdx create mode 100644 sdk/python/reference/show-user.mdx create mode 100644 sdk/python/reference/show-volumes.mdx create mode 100644 sdk/python/reference/show-workergroups.mdx create mode 100644 sdk/python/reference/ssh-url.mdx create mode 100644 sdk/python/reference/start-instance.mdx create mode 100644 sdk/python/reference/start-instances.mdx create mode 100644 sdk/python/reference/stop-instance.mdx create mode 100644 sdk/python/reference/stop-instances.mdx create mode 100644 sdk/python/reference/take-snapshot.mdx create mode 100644 sdk/python/reference/tfa-activate.mdx create mode 100644 sdk/python/reference/tfa-delete.mdx create mode 100644 sdk/python/reference/tfa-login.mdx create mode 100644 sdk/python/reference/tfa-regen-codes.mdx create mode 100644 sdk/python/reference/tfa-resend-sms.mdx create mode 100644 sdk/python/reference/tfa-send-sms.mdx create mode 100644 sdk/python/reference/tfa-status.mdx create mode 100644 sdk/python/reference/tfa-totp-setup.mdx create mode 100644 sdk/python/reference/tfa-update.mdx create mode 100644 sdk/python/reference/transfer-credit.mdx create mode 100644 sdk/python/reference/unlist-machine.mdx create mode 100644 sdk/python/reference/unlist-network-volume.mdx create mode 100644 sdk/python/reference/unlist-volume.mdx create mode 100644 sdk/python/reference/update-endpoint.mdx create mode 100644 sdk/python/reference/update-env-var.mdx create mode 100644 sdk/python/reference/update-instance.mdx create mode 100644 sdk/python/reference/update-ssh-key.mdx create mode 100644 sdk/python/reference/update-team-role.mdx create mode 100644 sdk/python/reference/update-template.mdx create mode 100644 sdk/python/reference/update-workergroup.mdx create mode 100644 sdk/python/reference/update-workers.mdx create mode 100644 sdk/python/reference/vastai.mdx create mode 100644 sdk/python/serverless/benchmark-config.mdx create mode 100644 sdk/python/serverless/client-worker.mdx create mode 100644 sdk/python/serverless/endpoint.mdx create mode 100644 sdk/python/serverless/handler-config.mdx create mode 100644 sdk/python/serverless/log-action-config.mdx create mode 100644 sdk/python/serverless/server-worker.mdx create mode 100644 sdk/python/serverless/serverless-request.mdx create mode 100644 sdk/python/serverless/serverless.mdx create mode 100644 sdk/python/serverless/session.mdx create mode 100644 sdk/python/serverless/worker-config.mdx create mode 100644 sdk/python/templates.mdx diff --git a/api-reference/authentication.mdx b/api-reference/authentication.mdx new file mode 100644 index 0000000..08a3d66 --- /dev/null +++ b/api-reference/authentication.mdx @@ -0,0 +1,97 @@ +--- +title: "Authentication" +sidebarTitle: "Authentication" +--- + +Every request to the Vast.ai API must include an API key. This page covers how to create keys, how to include them in requests, and key lifecycle details. + +## Create an API Key + +Generate a key from the [Keys page](https://cloud.vast.ai/cli/keys/) in the web console: + +1. Click **+New**. +2. Give the key a name (optional but recommended — e.g. "CI pipeline" or "notebook"). +3. Copy the key immediately — you'll only see it once. + + +You can also create keys programmatically via the API ([Create API Key](/api-reference/accounts/create-api-key)), CLI ([`vastai create api-key`](/cli/reference/create-api-key)), or SDK ([`vast.create_api_key()`](/sdk/python/reference/create-api-key)). + + +## Use an API Key + +Include your key as a Bearer token in the `Authorization` header: + + +```bash cURL +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + "https://console.vast.ai/api/v0/users/current/" +``` + +```python Python +import os +import requests + +headers = {"Authorization": f"Bearer {os.environ['VAST_API_KEY']}"} +resp = requests.get("https://console.vast.ai/api/v0/users/current/", headers=headers) +print(resp.json()) +``` + + +A common pattern is to store your key in an environment variable: + +```bash +export VAST_API_KEY="your-api-key-here" +``` + +This keeps the key out of your code and makes it easy to rotate. + + +If you get a `401 Unauthorized` or `403 Forbidden` response, double-check your API key. The most common causes are a typo, an expired key, or a scoped key that lacks the required permission for the endpoint you're calling. + + +## Verify Your Key + +A quick way to confirm your key works is to fetch your account info: + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + "https://console.vast.ai/api/v0/users/current/" +``` + +A successful response includes your user ID, email, balance, and SSH key: + +```json +{ + "id": 123456, + "email": "you@example.com", + "credit": 25.00, + "ssh_key": "ssh-rsa AAAAB3..." +} +``` + +## Scoped Keys and Permissions + +By default, the web console creates a **full-access** key. For CI/CD pipelines, shared tooling, or team environments, you should create **scoped keys** that restrict access to only the permissions you need. + +For example, a key that can only read and manage instances (but cannot access billing): + +```json +{ + "api": { + "misc": {}, + "user_read": {}, + "instance_read": {}, + "instance_write": {} + } +} +``` + +See the [Permissions](/api-reference/permissions) page for the full list of permission categories, endpoint mappings, constraint syntax, and advanced examples. + +## Key Expiration + +API keys do not expire by default. You can revoke a key at any time from the [Keys page](https://cloud.vast.ai/cli/keys/) or by calling the [Delete API Key](/api-reference/accounts/delete-api-key) endpoint. + + +Treat your API key like a password. Do not commit keys to version control or share them in plaintext. If a key is compromised, revoke it immediately and create a new one. + diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 26c7e84..0dcad5b 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -1,9 +1,186 @@ --- -title: "API Introduction" +title: "API Hello World" +sidebarTitle: "API Hello World" --- -**The raw REST API is intended for advanced users only.** These endpoints offer maximum flexibility but require you to manage all aspects of integration yourself. Most users will have a significantly better experience using the [CLI](/cli/get-started) or the [Python SDK](/sdk/python/quickstart), which handle these details for you. **If you are not sure whether you need direct API access, you almost certainly don't** — start with the CLI or SDK instead. + The raw REST API is intended for advanced users only. These endpoints offer maximum flexibility but require you to manage all aspects of integration yourself. Most users will have a significantly better experience using the [CLI](/cli/hello-world) or the [Python SDK](/sdk/python/quickstart), which handle these details for you. If you are not sure whether you need direct API access, you almost certainly don't — start with the CLI or SDK instead. -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. \ No newline at end of file +The Vast.ai REST API gives you programmatic control over GPU instances — useful for automation, CI/CD pipelines, or building your own tooling on top of Vast. + +This guide walks through the complete instance lifecycle: authenticate, search for a GPU, rent it, wait for it to boot, connect to it, and clean up. By the end you'll understand the core API calls needed to manage instances without touching the web console. + +## Prerequisites + +- A Vast.ai account with credit (~$0.01–0.05, depending on test instance run time) +- `curl` installed + +## 1. Get Your API Key + +Generate an API key from the [Keys page](https://cloud.vast.ai/cli/keys/) by clicking **+New**. Copy the key — you'll need it for your API calls, and you'll only see it once. + +Export it as an environment variable: + +```bash +export VAST_API_KEY="your-api-key-here" +``` + +## 2. Verify Authentication + +Confirm your key works by listing your current instances. If you have none, this returns an empty list. + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + "https://console.vast.ai/api/v0/instances/" +``` + +```json +{ + "instances_found": 0, + "instances": [] +} +``` + + +If you get a `401` or `403`, double-check your API key. If you already have instances, you'll see them listed here. + + +## 3. Search for GPUs + +Find available machines using the bundles endpoint. This query returns the top 5 on-demand RTX 4090s sorted by deep learning performance benchmarked per dollar: + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "verified": {"eq": true}, + "rentable": {"eq": true}, + "gpu_name": {"eq": "RTX 4090"}, + "num_gpus": {"eq": 1}, + "direct_port_count": {"gte": 1}, + "order": [["dlperf_per_dphtotal", "desc"]], + "type": "on-demand", + "limit": 5 + }' \ + "https://console.vast.ai/api/v0/bundles/" +``` + +Each parameter in the query above controls a different filter: + +| Parameter | Value | Meaning | +|-----------|-------|---------| +| `verified` | `{"eq": true}` | Only machines verified by Vast.ai (identity-checked hosts) | +| `rentable` | `{"eq": true}` | Only machines currently available to rent | +| `gpu_name` | `{"eq": "RTX 4090"}` | Filter to a specific GPU model | +| `num_gpus` | `{"eq": 1}` | Exactly 1 GPU per instance | +| `direct_port_count` | `{"gte": 1}` | At least 1 directly accessible port (needed for SSH) | +| `order` | `[["dlperf_per_dphtotal", "desc"]]` | Sort by deep learning performance per dollar, best value first | +| `type` | `"on-demand"` | On-demand pricing (vs. interruptible spot/bid) | +| `limit` | `5` | Return at most 5 results | + +The response contains an `offers` array. Note the `id` of the offer you want — you'll use it in the next step. If no offers are returned, try relaxing your filters (e.g. a different GPU model or removing `direct_port_count`). + + +See the [Search Offers](/api-reference/search/search-offers) reference for the full list of filter parameters and operators. + + +## 4. Create an Instance + +Rent the machine by sending a PUT request with your Docker image and disk size. Replace `OFFER_ID` with the `id` from step 3. `disk` is in GB and specifies the size of the disk on your new instance. + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + -H "Content-Type: application/json" \ + -X PUT \ + -d '{ + "image": "pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime", + "disk": 20, + "onstart": "echo hello && nvidia-smi" + }' \ + "https://console.vast.ai/api/v0/asks/OFFER_ID/" +``` + +```json +{ + "success": true, + "new_contract": 12345678, + "instance_api_key": "d15a..." +} +``` + +Save the `new_contract` value — this is your instance ID. The `instance_api_key` is a restricted key injected into the container as `CONTAINER_API_KEY` — it can only start, stop, or destroy that specific instance. + +## 5. Wait Until Ready + +The instance needs time to pull the Docker image and boot. Poll the status endpoint until `actual_status` is `"running"`. Replace `INSTANCE_ID` with the `new_contract` value from step 4. + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + "https://console.vast.ai/api/v0/instances/INSTANCE_ID/" +``` + +Example response: + +```json +{ + "instances": { + "actual_status": "loading", + "ssh_host": "...", + "ssh_port": 12345 + } +} +``` + +The `actual_status` field progresses through these states: + +| `actual_status` | Meaning | +|-----------------|---------| +| `null` | Instance is being provisioned | +| `"loading"` | Docker image is downloading | +| `"running"` | Ready to use | + +Poll every 10 seconds. Boot time is typically 1–5 minutes depending on the Docker image size. You can also use the `onstart` script to send a callback when the instance is ready, instead of polling. + +Once `actual_status` is `"running"`, you're ready to connect. + +## 6. Connect via SSH + +Use the `ssh_host` and `ssh_port` from the status response to connect directly to your new instance: + +```bash +ssh root@SSH_HOST -p SSH_PORT +``` + +## 7. Clean Up + +When you're done, destroy the instance to stop all billing. + +Alternatively, to pause an instance temporarily instead of destroying it, you can **stop** it. Stopping halts compute billing but disk storage charges continue. + +**Destroy** (removes everything): + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + -X DELETE \ + "https://console.vast.ai/api/v0/instances/INSTANCE_ID/" +``` + +**Stop** (pauses compute, disk charges continue): + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + -H "Content-Type: application/json" \ + -X PUT \ + -d '{"state": "stopped"}' \ + "https://console.vast.ai/api/v0/instances/INSTANCE_ID/" +``` + +Both return `{"success": true}`. + +## Next Steps + +You've now completed the full instance lifecycle through the API: authentication, search, creation, polling, and teardown. From here: + +- **SSH setup** — See the [SSH guide](/documentation/instances/connect/ssh) for key configuration and advanced connection options. +- **Use templates** — Avoid repeating image and config parameters on every create call. The [Templates API guide](/api-reference/creating-and-using-templates-with-api) covers creating, sharing, and launching from templates. diff --git a/api-reference/permissions.mdx b/api-reference/permissions.mdx new file mode 100644 index 0000000..1c08e4b --- /dev/null +++ b/api-reference/permissions.mdx @@ -0,0 +1,238 @@ +--- +title: "Permissions" +sidebarTitle: "Permissions" +--- + +Every API key has a set of permissions that control which endpoints it can access. This page is the comprehensive reference for permission categories, how they map to API routes, and how to build custom scoped keys. + +For an overview of API key creation and usage, see [Authentication](/api-reference/authentication). + +## Permission Categories + +Permissions are organized into categories. When you create a scoped API key, you include only the categories the key needs. The available categories are: + +| Category | Controls | +|----------|----------| +| `instance_read` | Viewing instances, logs, SSH keys, volumes, deposits | +| `instance_write` | Creating, managing, and destroying instances and volumes | +| `user_read` | Viewing account info, API keys, SSH keys, environment variables, templates | +| `user_write` | Creating/modifying API keys, SSH keys, environment variables, templates, teams | +| `billing_read` | Viewing invoices and earnings | +| `billing_write` | Transferring credit | +| `machine_read` | Viewing machines and reports (hosts) | +| `machine_write` | Managing machines, maintenance, listing/unlisting (hosts) | +| `misc` | Search offers, benchmarks, network volumes, serverless endpoints | +| `team_read` | Viewing team members and roles | +| `team_write` | Inviting/removing team members, managing roles | + +## Creating Scoped Keys + +Define permissions as a JSON object and pass it when creating a key. The top-level key is always `"api"`, containing the categories you want to grant. + +**Example — Instance management with billing access:** + +```json +{ + "api": { + "misc": {}, + "user_read": {}, + "instance_read": {}, + "instance_write": {}, + "billing_read": {}, + "billing_write": {} + } +} +``` + +**Example — Instance management without billing:** + +```json +{ + "api": { + "misc": {}, + "user_read": {}, + "instance_read": {}, + "instance_write": {} + } +} +``` + +You can create scoped keys using: +- **API**: [Create API Key](/api-reference/accounts/create-api-key) +- **CLI**: [`vastai create api-key`](/cli/reference/create-api-key) +- **SDK**: [`vast.create_api_key()`](/sdk/python/reference/create-api-key) + +## Custom Roles + +Custom roles let you assign the same set of permissions to multiple team members. + +- **Creating roles**: Use the CLI or the Manage page in the web console (requires `team_write` access). +- **Defining permissions**: Select from any combination of the categories listed above. +- **Assigning roles**: Assign created roles to team members through the team management interface or CLI. + +## Constraints + +Constraints narrow a permission category to specific parameter values. This lets you create keys that can only operate on certain resources. + +**Example — Read logs for a single instance only:** + +```json +{ + "api": { + "instance_read": { + "api.instance.request_logs": { + "constraints": { + "id": { + "eq": 1227 + } + } + } + } + } +} +``` + +**Example — Read logs for a range of instance IDs:** + +```json +{ + "api": { + "instance_read": { + "api.instance.request_logs": { + "constraints": { + "id": { + "lte": 2, + "gte": 1 + } + } + } + } + } +} +``` + +Supported constraint operators: `eq`, `lte`, `gte`. + + +API keys using constraints must be created via the CLI ([`vastai create api-key`](/cli/reference/create-api-key)) or the API ([Create API Key](/api-reference/accounts/create-api-key)). + + +You can also use **wildcards** in `params` to represent placeholder values — useful when generating many keys that perform similar operations. + +## Endpoint Reference by Category + +Below is the complete mapping of which endpoints each permission category controls. + +### instance\_read + +- [Show Instance](/api-reference/instances/show-instance) +- [Show Instances](/api-reference/instances/show-instances) +- [Show Logs](/api-reference/instances/show-logs) +- [Show SSH Keys](/api-reference/instances/show-ssh-keys) +- [Show Volumes](/api-reference/volumes/list-volumes) +- [Show Deposit](/api-reference/billing/show-deposit) + +### instance\_write + +- [Attach SSH Key](/api-reference/instances/attach-ssh-key) +- [Copy](/api-reference/instances/copy) +- [Cancel Copy](/api-reference/instances/cancel-copy) +- [Cloud Copy](/api-reference/instances/cloud-copy) +- [Cancel Sync](/api-reference/instances/cancel-sync) +- [Change Bid](/api-reference/instances/change-bid) +- [Create Instance](/api-reference/instances/create-instance) +- [Manage Instance](/api-reference/instances/manage-instance) +- [Delete Instance](/api-reference/instances/destroy-instance) +- [Detach SSH Key](/api-reference/instances/detach-ssh-key) +- [Execute](/api-reference/instances/execute) +- [Prepay Instance](/api-reference/instances/prepay-instance) +- [Reboot Instance](/api-reference/instances/reboot-instance) +- [Recycle Instance](/api-reference/instances/recycle-instance) +- [Create Volume](/api-reference/volumes/rent-volume) +- [Delete Volume](/api-reference/volumes/delete-volume) + +### user\_read + +- [Show API Keys](/api-reference/accounts/show-api-keys) +- [Show Connections](/api-reference/accounts/show-connections) +- [Show Environment Variables](/api-reference/accounts/show-env-vars) +- [Show IP Addresses](/api-reference/accounts/show-ipaddrs) +- [Show SSH Keys](/api-reference/accounts/show-ssh-keys) +- [Show Subaccounts](/api-reference/accounts/show-subaccounts) +- [Show User](/api-reference/accounts/show-user) +- [Search Templates](/api-reference/search/search-template) + +### user\_write + +- [Create API Key](/api-reference/accounts/create-api-key) +- [Delete API Key](/api-reference/accounts/delete-api-key) +- [Create Environment Variable](/api-reference/accounts/create-env-var) +- [Update Environment Variable](/api-reference/accounts/update-env-var) +- [Delete Environment Variable](/api-reference/accounts/delete-env-var) +- [Create SSH Key](/api-reference/accounts/create-ssh-key) +- [Update SSH Key](/api-reference/accounts/update-ssh-key) +- [Delete SSH Key](/api-reference/accounts/delete-ssh-key) +- [Create Subaccount](/api-reference/accounts/create-subaccount) +- [Set User](/api-reference/accounts/set-user) +- [Create Team](/api-reference/team/create-team) +- [Delete Team](/api-reference/team/destroy-team) +- [Create Template](/api-reference/templates/create-template) +- [Edit Template](/api-reference/templates/edit-template) +- [Delete Template](/api-reference/templates/delete-template) + +### billing\_read + +- [Search Invoices](/api-reference/billing/search-invoices) +- [Show Invoices](/api-reference/billing/show-invoices) +- [Show Earnings](/api-reference/billing/show-earnings) + +### billing\_write + +- [Transfer Credit](/api-reference/accounts/transfer-credit) + +### machine\_read + +- [Show Machines](/api-reference/machines/show-machines) +- [Show Reports](/api-reference/machines/show-reports) + +### machine\_write + +- [Cancel Maintenance](/api-reference/machines/cancel-maint) +- [Cleanup Machine](/api-reference/machines/cleanup-machine) +- [List Machine](/api-reference/machines/list-machine) +- [Remove Default Job](/api-reference/machines/remove-defjob) +- [Schedule Maintenance](/api-reference/machines/schedule-maint) +- [Set Default Job](/api-reference/machines/set-defjob) +- [Set Minimum Bid](/api-reference/machines/set-min-bid) +- [Unlist Machine](/api-reference/machines/unlist-machine) +- [Add Network Disk](/api-reference/network-volumes/add-network-disk) +- [Unlist Network Volume](/api-reference/network-volumes/unlist-network-volume) +- [Unlist Volume](/api-reference/volumes/unlist-volume) + +### misc + +- [Search Network Volumes](/api-reference/network-volumes/search-network-volumes) +- [Show Workergroups](/api-reference/serverless/show-workergroup) +- [Create Workergroup](/api-reference/serverless/create-workergroup) +- [Update Workergroup](/api-reference/serverless/update-workergroup) +- [Delete Workergroup](/api-reference/serverless/delete-workergroup) +- [Show Endpoints](/api-reference/serverless/show-endpoints) +- [Create Endpoint](/api-reference/serverless/create-endpoint) +- [Delete Endpoint](/api-reference/serverless/delete-endpoint) +- [Search Benchmarks](/api-reference/search/search-benchmarks) +- [Search Offers](/api-reference/search/search-offers) +- [Search Volumes](/api-reference/volumes/search-volumes) + +### team\_read + +- [Show Team Members](/api-reference/team/show-team-members) +- [Show Team Role](/api-reference/team/show-team-role) +- [Show Team Roles](/api-reference/team/show-team-roles) + +### team\_write + +- [Invite Team Member](/api-reference/team/invite-team-member) +- [Remove Team Member](/api-reference/team/remove-team-member) +- [Create Team Role](/api-reference/team/create-team-role) +- [Update Team Role](/api-reference/team/update-team-role) +- [Remove Team Role](/api-reference/team/remove-team-role) diff --git a/cli/authentication.mdx b/cli/authentication.mdx new file mode 100644 index 0000000..bfa8efc --- /dev/null +++ b/cli/authentication.mdx @@ -0,0 +1,103 @@ +--- +title: "CLI Authentication" +sidebarTitle: "Authentication" +--- + +Every request to the Vast.ai API requires an API key. The CLI stores your key locally and includes it automatically in every command. This page covers how to set up, verify, and manage API keys through the CLI. + +## Set Your API Key + +After creating a key from the [Keys page](https://cloud.vast.ai/cli/keys/), store it locally: + +```bash +vastai set api-key YOUR_API_KEY +``` + +This writes the key to `~/.config/vastai/vast_api_key` (or `$XDG_CONFIG_HOME/vastai/vast_api_key` if that env var is set). All subsequent commands use it automatically. + +## Environment Variable (CI/CD) + +Instead of storing the key in a file, you can set it as an environment variable: + +```bash +export VAST_API_KEY="your_api_key_here" +``` + +This is recommended for CI pipelines, Docker containers, and scripts — it avoids writing keys to +disk and makes it easy to inject secrets via your platform's secret manager. The environment +variable takes precedence over the file if both are set. + + +If you previously used an older version of the CLI, your key may be at the legacy location +`~/.vast_api_key`. The CLI migrates it automatically to `~/.config/vastai/vast_api_key` on next +run, so no manual action is needed. + + +## Verify Your Key + +Confirm your key works by fetching your account info: + +```bash +vastai show user +``` + +A successful response includes your user ID, email, and balance: + +```json +{ + "id": 123456, + "email": "you@example.com", + "credit": 25.00, + "ssh_key": "ssh-rsa AAAAB3..." +} +``` + + +If you get an authentication error, double-check your API key. The most common causes are a typo, an expired key, or a scoped key that lacks the required permission for the command you're running. + + +## Create an API Key + +You can create new keys from the CLI: + +```bash +vastai create api-key --name "ci-deploy-key" +``` + +The output includes the new key value. Copy it immediately -- you will not be able to retrieve it again. + +To create a key with restricted permissions, pass a JSON permissions file: + +```bash +vastai create api-key --name "ci-deploy-key" --permission_file perms.json +``` + +See the [Permissions](/cli/permissions) page for the full permissions file format and examples. + +## View and Delete Keys + +List all API keys on your account: + +```bash +vastai show api-keys +``` + +View a specific key's details by ID: + +```bash +vastai show api-key 42 +``` + +Delete a key: + +```bash +vastai delete api-key 42 +``` + +## Key Expiration + +API keys do not expire by default. You can revoke a key at any time from the [Keys page](https://cloud.vast.ai/cli/keys/) or with `vastai delete api-key`. + + +Treat your API key like a password. Do not commit keys to version control or share them in plaintext. If a key is compromised, revoke it immediately and create a new one. + diff --git a/cli/commands.mdx b/cli/commands.mdx deleted file mode 100644 index 473d831..0000000 --- a/cli/commands.mdx +++ /dev/null @@ -1,2097 +0,0 @@ ---- -title: Commands -createdAt: Mon Jan 13 2025 21:20:40 GMT+0000 (Coordinated Universal Time) -updatedAt: Sat Jul 12 2025 01:09:10 GMT+0000 (Coordinated Universal Time) ---- - -