Create a VM with the API

This page creates a small VM, waits until it runs, reads how to log in, and deletes it again. You need an API key and some credit: see The Doprax API.

export DOPRAX_API_URL=https://www.doprax.com
export DOPRAX_API_KEY=your-key

Caution

Step 2 creates a real VM that is charged by the hour until you delete it in step 5.

1. Pick a plan

List the plans of one provider. provm is Doprax’s own hardware.

curl -sS "$DOPRAX_API_URL/api/v3/catalogue/plans/?service_type=vm&provider=provm" \
  -H "X-API-Key: $DOPRAX_API_KEY"

Answer

{
  "success": true,
  "data": [
    {
      "plan": "P1",
      "product_version_id": "367e0f33-4cf5-498e-9537-cf6d74632e9c",
      "service_type": "vm",
      "provider": "ProVM",
      "provider_code": "provm",
      "cpu": 1.0,
      "ram_gb": 1.0,
      "disk_gb": 20.0,
      "locations": [
        {
          "name": "Poland",
          "code": "provm_019b3cb3-3bc8-73e2-8aba-7edcad26ed0f"
        },
        {
          "name": "UK",
          "code": "provm_019ac0e3-500c-7e67-a7da-e6ac9916ac1b"
        }
      ],
      "monthly_price": 7.95,
      "currency": "USD"
    },
    {
      "plan": "P2",
      "product_version_id": "48178144-c6ff-4d20-b6dd-8e43d2deb396",
      "service_type": "vm",
      "provider": "ProVM",
      "provider_code": "provm",
      "cpu": 1.0,
      "ram_gb": 2.0,
      "disk_gb": 30.0,
      "locations": [
        {
          "name": "Poland",
          "code": "provm_019b3cb3-3bc8-73e2-8aba-7edcad26ed0f"
        },
        {
          "name": "UK",
          "code": "provm_019ac0e3-500c-7e67-a7da-e6ac9916ac1b"
        }
      ],
      "monthly_price": 12.95,
      "currency": "USD"
    }
  ]
}

Each plan has a name, its size, its price per month and the locations where it can run. The answer above is cut to two plans and two locations to keep the page short.

2. Create the VM

Name the plan, the location and the operating system in words. You do not need any ids.

curl -sS -X POST "$DOPRAX_API_URL/api/v3/services/" \
  -H "X-API-Key: $DOPRAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service_type": "vm",
    "plan": "P1",
    "location": "Poland",
    "os": "ubuntu_24_04",
    "name": "my-first-vm",
    "idempotency_key": "'"$IDEMPOTENCY_KEY"'"
  }'

Answer

{
  "operation_id": "c725787d-7d98-40f5-b155-40ca5127e660",
  "service_id": "187030b1-dd8d-4a50-95bb-7dd0ca4acf1c",
  "status": "pending",
  "action": "create",
  "task_id": "<hidden>",
  "status_reason": null,
  "created_at": "2026-10-12T05:36:06.703Z",
  "started_at": null,
  "completed_at": null,
  "updated_at": "2026-10-12T05:36:06.703Z",
  "success": true,
  "resolved": {
    "plan": "P1",
    "location": "provm_019b3cb3-3bc8-73e2-8aba-7edcad26ed0f",
    "os": "ubuntu_24_04"
  }
}

• service_id is the VM’s id for every later request.
• resolved says what your words were turned into.
• idempotency_key is any text of your own. Sending the same request again with the same key does not create a second VM.
• os is optional. Without it you get Ubuntu.

If a word does not match exactly one choice, nothing is created and the answer lists the choices. For example, leaving out location on a plan that runs in several places gives status 400 with:

{
  "success": false,
  "error": "location_required",
  "plan": "P1",
  "available_locations": [
    { "name": "Poland", "code": "provm_019b3cb3-3bc8-73e2-8aba-7edcad26ed0f" },
    { "name": "UK", "code": "provm_019ac0e3-500c-7e67-a7da-e6ac9916ac1b" }
  ]
}

error	Meaning	The answer also has
plan_not_found	No plan has that name	available_plans
plan_ambiguous	Several plans match	matches
location_required	The plan runs in several places; say which	available_locations
location_not_allowed	The plan does not run there	available_locations
location_ambiguous	Several locations match, for example two cities in one country	matches
os_not_allowed	The plan does not offer that system	available_os
os_ambiguous	Several systems match, for example ubuntu with two versions; use a code from matches	matches

3. Wait until it runs

Ask for the VM every ten seconds until status is running. On ProVM that takes about a minute. On the way you see provisioning and starting.

curl -sS "$DOPRAX_API_URL/api/v2/services/instances/$SERVICE_ID/" \
  -H "X-API-Key: $DOPRAX_API_KEY"

Answer

{
  "success": true,
  "data": {
    "service": {
      "service_id": "187030b1-dd8d-4a50-95bb-7dd0ca4acf1c",
      "name": "my-first-vm",
      "description": null,
      "status": "running",
      "status_reason": "vm_setup_complete",
      "service_type": "vm",
      "product_version_id": "367e0f33-4cf5-498e-9537-cf6d74632e9c",
      "product": {
        "name": "P1",
        "version": 1
      },
      "provider": {
        "code": "provm",
        "name": "ProVM"
      },
      "metadata": {
        "vm_code": "0eb0c974-8aff-46c6-904a-83b1053e72d8"
      },
      "created_at": "2026-10-12T05:36:07.545Z",
      "updated_at": "2026-10-12T05:36:06.698Z",
      "activated_at": "2026-10-12T05:37:08.142Z",
      "location": null,
      "open_alerts": 0
    },
    "access": {
      "username": "root",
      "public_ipv4": "203.0.113.10",
      "public_ipv6": "2001:db8::10",
      "active_ssh_key": null,
      "authentication_type": "password",
      "web_ui_url": null
    }
  }
}

access.public_ipv4 is the address to connect to. metadata.vm_code is needed for the next step.

4. Read how to log in

curl -sS "$DOPRAX_API_URL/api/v2/vms/$VM_CODE/actions/access/" \
  -H "X-API-Key: $DOPRAX_API_KEY"

Answer

{
  "success": true,
  "data": {
    "tempPass": "<password>",
    "vmUsername": "root",
    "accessMethod": "password",
    "userPublicSSHKeyFingerprint": null,
    "userPublicSSHKeyTitle": null
  },
  "error": null,
  "meta": {
    "pagination": {}
  }
}

$VM_CODE is metadata.vm_code from step 3. This VM was created without an SSH key, so it got a generated password: log in with ssh root@<public_ipv4> and the value of tempPass.

5. Delete it

curl -sS -X POST "$DOPRAX_API_URL/api/v2/services/instances/$SERVICE_ID/operations/" \
  -H "X-API-Key: $DOPRAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "delete", "idempotency_key": "'"$IDEMPOTENCY_KEY-delete"'"}'

Answer

{
  "success": true,
  "data": {
    "operation_id": "6cc2ca76-3ae7-4fc0-bad8-e44746cb8c65",
    "service_id": "187030b1-dd8d-4a50-95bb-7dd0ca4acf1c",
    "status": "pending",
    "action": "delete",
    "task_id": "<hidden>",
    "status_reason": null,
    "created_at": "2026-10-12T05:37:11.673Z",
    "started_at": null,
    "completed_at": null,
    "updated_at": "2026-10-12T05:37:11.673Z"
  },
  "error": null,
  "meta": {
    "pagination": {}
  }
}

Deleting ends the charge and cannot be undone. Other operations go to the same address with a different action: start, stop, reboot. See the reference.