From 3c9114f1fb3ff8bd2c2754c96c8fd6dd35f4438a Mon Sep 17 00:00:00 2001 From: Will Brennan Date: Wed, 11 Feb 2026 16:12:35 -0700 Subject: [PATCH 1/5] docs: add API Hello World guide --- api-reference/hello-world.mdx | 174 ++++++++++++++++++++++++++++++++++ docs.json | 1 + 2 files changed, 175 insertions(+) create mode 100644 api-reference/hello-world.mdx diff --git a/api-reference/hello-world.mdx b/api-reference/hello-world.mdx new file mode 100644 index 0000000..eef05cf --- /dev/null +++ b/api-reference/hello-world.mdx @@ -0,0 +1,174 @@ +--- +title: "API Hello World" +sidebarTitle: "Hello World" +--- + +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, 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 +- `curl` installed + +## 1. Get Your API Key + +Generate an API key from the Vast.ai console at [cloud.vast.ai](https://cloud.vast.ai/). Copy the key — you'll need it for every API call. + +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. + + +## 3. Search for GPUs + +Find available machines using the bundles endpoint. This query returns the 3 cheapest on-demand RTX 4090s (sorted by total $/hr, including storage): + +```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": [["dph_total", "asc"]], + "type": "on-demand", + "limit": 3 + }' \ + "https://console.vast.ai/api/v0/bundles/" +``` + +Here's what each parameter does: + +| 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` | `[["dph_total", "asc"]]` | Sort by total cost per hour, cheapest first | +| `type` | `"on-demand"` | On-demand pricing (vs. interruptible spot/bid) | +| `limit` | `3` | Return at most 3 results | + +The response contains an `offers` array. Note the `id` of the offer you want — you'll use it in the next step. + + +All filters use operator objects like `{"eq": true}` or `{"gte": 1}`. The sort field must be `"order": [["field", "direction"]]` (array of arrays). + + +## 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. + +```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 response also includes an `instance_api_key` for programmatic access to the 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. + +Once `actual_status` is `"running"`, you can connect via SSH using the `ssh_host` and `ssh_port` from the response. + +## 6. Clean Up + +When you're done, destroy the instance to stop all billing. + +To pause an instance temporarily instead of destroying it, you can **stop** it. Stopping halts compute billing but disk storage charges continue. + +**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/" +``` + +**Destroy** (removes everything): + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + -X DELETE \ + "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: + +- **Connect via SSH** — Once an instance is running, use the `ssh_host` and `ssh_port` from the status response to SSH in. See the [SSH guide](/documentation/instances/connect/ssh) for setup. +- **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/docs.json b/docs.json index e5b8300..7007ea1 100644 --- a/docs.json +++ b/docs.json @@ -361,6 +361,7 @@ "icon": "webhook", "pages": [ "api-reference/introduction", + "api-reference/hello-world", "api-reference/permissions-and-authorization", "api-reference/creating-and-using-templates-with-api", "api-reference/rate-limits-and-errors" From 86e2cdbe9f76f1ac58591f0646e7069fc3fb0702 Mon Sep 17 00:00:00 2001 From: "guthrie@vast.ai" Date: Thu, 12 Feb 2026 10:36:41 -0800 Subject: [PATCH 2/5] docs: revise API Hello World guide for accuracy and clarity - Fix API key generation link to point to Keys page - Change search sort to dlperf_per_dphtotal, increase limit to 5 - Add cost estimate, disk size clarification, instance_api_key description - Add SSH connection step (step 6), reorder clean up to step 7 - Swap destroy/stop order, add onstart callback mention - Link to Search Offers reference, consolidate Next Steps Co-Authored-By: Claude Opus 4.6 --- api-reference/hello-world.mdx | 58 ++++++++++++++++++++--------------- 1 file changed, 33 insertions(+), 25 deletions(-) diff --git a/api-reference/hello-world.mdx b/api-reference/hello-world.mdx index eef05cf..85201bc 100644 --- a/api-reference/hello-world.mdx +++ b/api-reference/hello-world.mdx @@ -5,16 +5,16 @@ sidebarTitle: "Hello World" 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, and clean up. By the end you'll understand the core API calls needed to manage instances without touching the web console. +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 +- 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 Vast.ai console at [cloud.vast.ai](https://cloud.vast.ai/). Copy the key — you'll need it for every API call. +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: @@ -39,12 +39,12 @@ curl -s -H "Authorization: Bearer $VAST_API_KEY" \ ``` -If you get a `401` or `403`, double-check your API key. +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 3 cheapest on-demand RTX 4090s (sorted by total $/hr, including storage): +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" \ @@ -55,14 +55,14 @@ curl -s -H "Authorization: Bearer $VAST_API_KEY" \ "gpu_name": {"eq": "RTX 4090"}, "num_gpus": {"eq": 1}, "direct_port_count": {"gte": 1}, - "order": [["dph_total", "asc"]], + "order": [["dlperf_per_dphtotal", "desc"]], "type": "on-demand", - "limit": 3 + "limit": 5 }' \ "https://console.vast.ai/api/v0/bundles/" ``` -Here's what each parameter does: +Each parameter in the query above controls a different filter: | Parameter | Value | Meaning | |-----------|-------|---------| @@ -71,19 +71,19 @@ Here's what each parameter does: | `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` | `[["dph_total", "asc"]]` | Sort by total cost per hour, cheapest first | +| `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` | `3` | Return at most 3 results | +| `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. +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`). -All filters use operator objects like `{"eq": true}` or `{"gte": 1}`. The sort field must be `"order": [["field", "direction"]]` (array of arrays). +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. +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" \ @@ -105,7 +105,7 @@ curl -s -H "Authorization: Bearer $VAST_API_KEY" \ } ``` -Save the `new_contract` value — this is your instance ID. The response also includes an `instance_api_key` for programmatic access to the instance. +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 @@ -136,31 +136,39 @@ The `actual_status` field progresses through these states: | `"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. +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 can connect via SSH using the `ssh_host` and `ssh_port` from the response. +Once `actual_status` is `"running"`, you're ready to connect. -## 6. Clean Up +## 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. -To pause an instance temporarily instead of destroying it, you can **stop** it. Stopping halts compute billing but disk storage charges continue. +Alternatively, to pause an instance temporarily instead of destroying it, you can **stop** it. Stopping halts compute billing but disk storage charges continue. -**Stop** (pauses compute, disk charges continue): +**Destroy** (removes everything): ```bash curl -s -H "Authorization: Bearer $VAST_API_KEY" \ - -H "Content-Type: application/json" \ - -X PUT \ - -d '{"state": "stopped"}' \ + -X DELETE \ "https://console.vast.ai/api/v0/instances/INSTANCE_ID/" ``` -**Destroy** (removes everything): +**Stop** (pauses compute, disk charges continue): ```bash curl -s -H "Authorization: Bearer $VAST_API_KEY" \ - -X DELETE \ + -H "Content-Type: application/json" \ + -X PUT \ + -d '{"state": "stopped"}' \ "https://console.vast.ai/api/v0/instances/INSTANCE_ID/" ``` @@ -170,5 +178,5 @@ Both return `{"success": true}`. You've now completed the full instance lifecycle through the API: authentication, search, creation, polling, and teardown. From here: -- **Connect via SSH** — Once an instance is running, use the `ssh_host` and `ssh_port` from the status response to SSH in. See the [SSH guide](/documentation/instances/connect/ssh) for setup. +- **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. From ab237017a314fb9845562ee0e77c11bea93963c1 Mon Sep 17 00:00:00 2001 From: "guthrie@vast.ai" Date: Thu, 12 Feb 2026 11:01:02 -0800 Subject: [PATCH 3/5] docs: make Hello World guide the API landing page Replace the minimal API introduction with the Hello World guide content, remove the now-redundant hello-world.mdx, and add a redirect. Co-Authored-By: Claude Opus 4.6 --- api-reference/hello-world.mdx | 182 -------------------------------- api-reference/introduction.mdx | 183 ++++++++++++++++++++++++++++++++- docs.json | 5 +- 3 files changed, 182 insertions(+), 188 deletions(-) delete mode 100644 api-reference/hello-world.mdx diff --git a/api-reference/hello-world.mdx b/api-reference/hello-world.mdx deleted file mode 100644 index 85201bc..0000000 --- a/api-reference/hello-world.mdx +++ /dev/null @@ -1,182 +0,0 @@ ---- -title: "API Hello World" -sidebarTitle: "Hello World" ---- - -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/introduction.mdx b/api-reference/introduction.mdx index 26c7e84..85201bc 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -1,9 +1,182 @@ --- -title: "API Introduction" +title: "API Hello World" +sidebarTitle: "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 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. -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 +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/docs.json b/docs.json index 7007ea1..4136657 100644 --- a/docs.json +++ b/docs.json @@ -361,7 +361,6 @@ "icon": "webhook", "pages": [ "api-reference/introduction", - "api-reference/hello-world", "api-reference/permissions-and-authorization", "api-reference/creating-and-using-templates-with-api", "api-reference/rate-limits-and-errors" @@ -740,6 +739,10 @@ "source": "/api", "destination": "/api-reference/introduction" }, + { + "source": "/api-reference/hello-world", + "destination": "/api-reference/introduction" + }, { "source": "/api/:slug*", "destination": "/api-reference/:slug*" From 4878de7d036fa8609f66af134f417a3cba5f1f11 Mon Sep 17 00:00:00 2001 From: Will Brennan Date: Mon, 23 Feb 2026 16:00:04 -0700 Subject: [PATCH 4/5] docs: add Python examples and preserve warning from main Add Python code tabs alongside curl for all API steps using CodeGroup. Restore advanced-users-only warning that was on main. --- api-reference/introduction.mdx | 110 +++++++++++++++++++++++++++++++-- 1 file changed, 104 insertions(+), 6 deletions(-) diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 85201bc..ef55af3 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -3,6 +3,10 @@ title: "API Hello World" sidebarTitle: "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 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. @@ -11,6 +15,7 @@ This guide walks through the complete instance lifecycle: authenticate, search f - A Vast.ai account with credit (~$0.01–0.05, depending on test instance run time) - `curl` installed +- `python3` with the `requests` library (for the Python examples) ## 1. Get Your API Key @@ -26,11 +31,25 @@ export VAST_API_KEY="your-api-key-here" Confirm your key works by listing your current instances. If you have none, this returns an empty list. -```bash + +```bash cURL curl -s -H "Authorization: Bearer $VAST_API_KEY" \ "https://console.vast.ai/api/v0/instances/" ``` +```python Python +import os +import requests + +VAST_API_KEY = os.environ["VAST_API_KEY"] +BASE_URL = "https://console.vast.ai/api/v0" +headers = {"Authorization": f"Bearer {VAST_API_KEY}"} + +resp = requests.get(f"{BASE_URL}/instances/", headers=headers) +print(resp.json()) +``` + + ```json { "instances_found": 0, @@ -46,7 +65,8 @@ If you get a `401` or `403`, double-check your API key. If you already have inst 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 + +```bash cURL curl -s -H "Authorization: Bearer $VAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{ @@ -62,6 +82,25 @@ curl -s -H "Authorization: Bearer $VAST_API_KEY" \ "https://console.vast.ai/api/v0/bundles/" ``` +```python Python +search_params = { + "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, +} + +resp = requests.post(f"{BASE_URL}/bundles/", headers=headers, json=search_params) +offers = resp.json()["offers"] +for offer in offers: + print(f"ID: {offer['id']} GPU: {offer['gpu_name']} $/hr: {offer['dph_total']}") +``` + + Each parameter in the query above controls a different filter: | Parameter | Value | Meaning | @@ -85,7 +124,8 @@ See the [Search Offers](/api-reference/search/search-offers) reference for the f 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 + +```bash cURL curl -s -H "Authorization: Bearer $VAST_API_KEY" \ -H "Content-Type: application/json" \ -X PUT \ @@ -97,6 +137,23 @@ curl -s -H "Authorization: Bearer $VAST_API_KEY" \ "https://console.vast.ai/api/v0/asks/OFFER_ID/" ``` +```python Python +offer_id = offers[0]["id"] # from step 3 + +create_params = { + "image": "pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime", + "disk": 20, + "onstart": "echo hello && nvidia-smi", +} + +resp = requests.put( + f"{BASE_URL}/asks/{offer_id}/", headers=headers, json=create_params +) +result = resp.json() +print(result) +``` + + ```json { "success": true, @@ -111,11 +168,34 @@ Save the `new_contract` value — this is your instance ID. The `instance_api_ke 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 + +```bash cURL curl -s -H "Authorization: Bearer $VAST_API_KEY" \ "https://console.vast.ai/api/v0/instances/INSTANCE_ID/" ``` +```python Python +import time + +instance_id = result["new_contract"] + +while True: + resp = requests.get(f"{BASE_URL}/instances/{instance_id}/", headers=headers) + instance = resp.json()["instances"] + if instance is None: + print("Status: provisioning") + time.sleep(10) + continue + status = instance.get("actual_status") + print(f"Status: {status}") + if status == "running": + break + time.sleep(10) + +print(f"SSH: ssh -p {instance['ssh_port']} root@{instance['ssh_host']}") +``` + + Example response: ```json @@ -156,15 +236,23 @@ Alternatively, to pause an instance temporarily instead of destroying it, you ca **Destroy** (removes everything): -```bash + +```bash cURL curl -s -H "Authorization: Bearer $VAST_API_KEY" \ -X DELETE \ "https://console.vast.ai/api/v0/instances/INSTANCE_ID/" ``` +```python Python +resp = requests.delete(f"{BASE_URL}/instances/{instance_id}/", headers=headers) +print(resp.json()) +``` + + **Stop** (pauses compute, disk charges continue): -```bash + +```bash cURL curl -s -H "Authorization: Bearer $VAST_API_KEY" \ -H "Content-Type: application/json" \ -X PUT \ @@ -172,6 +260,16 @@ curl -s -H "Authorization: Bearer $VAST_API_KEY" \ "https://console.vast.ai/api/v0/instances/INSTANCE_ID/" ``` +```python Python +resp = requests.put( + f"{BASE_URL}/instances/{instance_id}/", + headers=headers, + json={"state": "stopped"}, +) +print(resp.json()) +``` + + Both return `{"success": true}`. ## Next Steps From a8c6cf1b47140ba02c3b7fb6aa2371fb11610edd Mon Sep 17 00:00:00 2001 From: Will Brennan Date: Mon, 23 Feb 2026 16:07:21 -0700 Subject: [PATCH 5/5] docs: address PR feedback - scoped keys, /users/current, templates, ssh_direct, show instance link - Expand intro to describe full API scope - Add scoped API keys tip with link to Create API Key endpoint - Switch auth step to /users/current/ endpoint - Add template-based instance creation with link to Templates guide - Add ssh_direct runtype to create params - Fix instance_api_key description to include GET access - Add Show Instance endpoint link in polling section --- api-reference/introduction.mdx | 60 +++++++++++++++++++++++++++------- 1 file changed, 48 insertions(+), 12 deletions(-) diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index ef55af3..3089501 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -7,9 +7,9 @@ sidebarTitle: "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 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. +The Vast.ai REST API gives you programmatic access to the entire platform — authentication, account management, billing, GPU search, instance lifecycle, templates, volumes, serverless endpoints, and team administration. Anything you can do in the web console, you can automate through the API. -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. +This guide walks through the core workflow: 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 API calls needed to manage instances without touching the web console. ## Prerequisites @@ -27,14 +27,18 @@ Export it as an environment variable: export VAST_API_KEY="your-api-key-here" ``` + +The console creates a full-access key by default. You can also create scoped API keys with limited permissions via `POST /api/v0/auth/apikeys/` — useful for CI/CD or shared tooling where you want to restrict access to read-only or instance-only operations. See the [Create API Key](/api-reference/accounts/create-api-key) endpoint for details. + + ## 2. Verify Authentication -Confirm your key works by listing your current instances. If you have none, this returns an empty list. +Confirm your key works by fetching your account info. This returns your user ID, email, balance, and SSH key — a quick way to verify what your key grants access to. ```bash cURL curl -s -H "Authorization: Bearer $VAST_API_KEY" \ - "https://console.vast.ai/api/v0/instances/" + "https://console.vast.ai/api/v0/users/current/" ``` ```python Python @@ -45,20 +49,24 @@ VAST_API_KEY = os.environ["VAST_API_KEY"] BASE_URL = "https://console.vast.ai/api/v0" headers = {"Authorization": f"Bearer {VAST_API_KEY}"} -resp = requests.get(f"{BASE_URL}/instances/", headers=headers) +resp = requests.get(f"{BASE_URL}/users/current/", headers=headers) print(resp.json()) ``` ```json { - "instances_found": 0, - "instances": [] + "id": 123456, + "email": "you@example.com", + "credit": 25.00, + "ssh_key": "ssh-rsa AAAAB3..." } ``` +The `credit` field shows your available credit, and `ssh_key` is the public key that will be injected into new instances. + -If you get a `401` or `403`, double-check your API key. If you already have instances, you'll see them listed here. +If you get a `401` or `403`, double-check your API key. ## 3. Search for GPUs @@ -122,7 +130,27 @@ See the [Search Offers](/api-reference/search/search-offers) reference for the f ## 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. +Rent the machine by sending a PUT request to the asks endpoint. Replace `OFFER_ID` with the `id` from step 3. + +The simplest approach is to create from a **template**, which bundles your image, startup commands, and launch settings into a reusable configuration: + +```bash +curl -s -H "Authorization: Bearer $VAST_API_KEY" \ + -H "Content-Type: application/json" \ + -X PUT \ + -d '{ + "template_hash_id": "YOUR_TEMPLATE_HASH", + "disk": 20, + "runtype": "ssh_direct" + }' \ + "https://console.vast.ai/api/v0/asks/OFFER_ID/" +``` + + +A template packages your Docker image, environment variables, and startup script so you don't repeat them on every create call. See the [Templates API guide](/api-reference/creating-and-using-templates-with-api) for creating and managing templates. + + +If you don't have a template yet, you can specify the image and startup commands directly: ```bash cURL @@ -132,7 +160,8 @@ curl -s -H "Authorization: Bearer $VAST_API_KEY" \ -d '{ "image": "pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime", "disk": 20, - "onstart": "echo hello && nvidia-smi" + "onstart": "echo hello && nvidia-smi", + "runtype": "ssh_direct" }' \ "https://console.vast.ai/api/v0/asks/OFFER_ID/" ``` @@ -144,6 +173,7 @@ create_params = { "image": "pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime", "disk": 20, "onstart": "echo hello && nvidia-smi", + "runtype": "ssh_direct", } resp = requests.put( @@ -162,7 +192,11 @@ print(result) } ``` -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. +Save the `new_contract` value — this is your instance ID. The `instance_api_key` provides scoped access for that specific instance (e.g., querying `GET /api/v0/instances/{id}/` without your main API key). + + +Setting `"runtype": "ssh_direct"` gives you a direct SSH connection to the machine, which has lower latency than the default proxy SSH. Recommended for interactive work. + ## 5. Wait Until Ready @@ -218,7 +252,9 @@ The `actual_status` field progresses through these states: 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. +This endpoint returns extensive instance details (hardware specs, pricing, networking, utilization metrics, and more). See the [Show Instance](/api-reference/instances/show-instance) endpoint for the full field reference. + +Once `actual_status` is `"running"`, you're ready to connect. Since we set `runtype` to `ssh_direct` in step 4, this is a direct connection to the machine. ## 6. Connect via SSH