From d57707b386d75113515a73fdd2786a7f148bbf8c Mon Sep 17 00:00:00 2001 From: Will Brennan Date: Wed, 11 Feb 2026 16:12:35 -0700 Subject: [PATCH 1/3] 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 fb3f4df..c97896f 100644 --- a/docs.json +++ b/docs.json @@ -355,6 +355,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 4111a97aa08337f8a92c193ce11b2a7b4078403d Mon Sep 17 00:00:00 2001 From: "guthrie@vast.ai" Date: Thu, 12 Feb 2026 10:36:41 -0800 Subject: [PATCH 2/3] 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 2a7b0efbdec037920a167ddd40bc679c44559c76 Mon Sep 17 00:00:00 2001 From: "guthrie@vast.ai" Date: Thu, 12 Feb 2026 11:01:02 -0800 Subject: [PATCH 3/3] 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 | 181 +++++++++++++++++++++++++++++++- docs.json | 5 +- 3 files changed, 183 insertions(+), 185 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 c77a971..85201bc 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -1,5 +1,182 @@ --- -title: "API Introduction" +title: "API Hello World" +sidebarTitle: "Hello World" --- -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/docs.json b/docs.json index c97896f..793e458 100644 --- a/docs.json +++ b/docs.json @@ -355,7 +355,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" @@ -734,6 +733,10 @@ "source": "/api", "destination": "/api-reference/introduction" }, + { + "source": "/api-reference/hello-world", + "destination": "/api-reference/introduction" + }, { "source": "/api/:slug*", "destination": "/api-reference/:slug*"