---
title: "Create a rental"
method: POST
path: "/v2/on-demand/rentals"
tags: ["rentals"]
---

# Create a rental

`POST /v2/on-demand/rentals`

## Request

- Base URL: `https://api.hyperbolic.ai`
- URL: `https://api.hyperbolic.ai/v2/on-demand/rentals`
- Auth: HTTP bearer

Rent a virtual machine or a bare metal server. `rentalType` decides which machine-type-specific fields apply; sending a field for the other type is a BAD_REQUEST (INVALID_INPUT_FOR_RENTAL_TYPE).

## Request body

- object
  - `rentalType` 'virtual-machine' | 'bare-metal', required: The machine type to rent. Fields marked for one machine type are rejected for the other.
  - `gpuCount` number, required: GPUs to rent. Bare metal rents whole nodes, so a multiple of 8.
  - `networkType` 'infiniband' | 'ethernet': Required for bare metal. Virtual machines default to `ethernet`.
  - `region` union: A region that offers the chosen machine type.
    - 'us-central-1' | 'us-central-2' | 'eu-north-2' | 'eu-west-2' | 'eu-north-4' | 'eu-north-5' | 'us-east-1' | 'us-east-2' | 'ca-east-3' | 'eu-north-6' | 'eu-north-7' | 'eu-north-8' | 'eu-north-9' | 'ca-west-1' | 'ca-east-1' | 'us-central-3' | 'us-southeast-1' | 'me-central-1' | 'ca-east-2' | 'eu-west-1' | 'us-southeast-2' | 'jp-east-1' | 'us-southeast-3' | 'eu-west-5' | 'jp-east-2' | 'us-east-3'
    - 'us-central-1' | 'uk-central-3' | 'uk-southeast-3' | 'eu-southwest-3' | 'eu-southwest-3-1' | 'eu-west-3' | 'eu-west-4'
  - `gpuType` 'h100' | 'h200' | 'b200' | 'rtx-6000-pro'
  - `label` string
  - `termType` 'on-demand' | 'reserved'
  - `termPeriodDays` integer: Any whole number of days from 1 to 30 where custom reservation lengths are enabled for your account; otherwise one of the standard terms in `options` from `GET /v2/on-demand/reserve-options`.
  - `discountPercentage` number
  - `convertToOnDemandOnExpiry` boolean
  - `monitoringEnabled` boolean
  - `sshPublicKeyId` integer: The saved SSH key to authorize on the rental. Defaults to the most recently added key.
  - `sshPublicKeyIds` integer[]: The saved SSH keys to authorize on the rental.
  - `customPorts` integer[]: Virtual machines only.
  - `monitoringOptOut` boolean: Virtual machines only. Opt the rental out of Hyperbolic telemetry: the GPU health and system metrics (CPU, memory, root filesystem, network interfaces) Hyperbolic collects from inside the virtual machine to detect hardware faults. No logs, process lists or file contents are collected. Omitted or `false` leaves collection on. Only standalone virtual machine rentals in supported regions can opt out; elsewhere `true` gets a 400.
  - `cudaVersion` 'cuda12.8' | 'cuda12.9': Bare metal only.
  - `storageVolume` union: Bare metal only.
    - object
      - `isNew` false, required
      - `id` union, required
        - integer
        - string
    - object
      - `isNew` true, required
      - `label` string, required
      - `sizeInGb` integer, required

## Response `200`

Successful response

- Rental: A GPU rental.
  - `rentalId` string, required
  - `name` string, nullable, required
  - `label` string, nullable, required
  - `rentalType` 'virtual-machine' | 'bare-metal', required
  - `region` 'us-central-1' | 'us-central-2' | 'eu-north-2' | 'eu-west-2' | 'eu-north-4' | 'eu-north-5' | 'us-east-1' | 'us-east-2' | 'ca-east-3' | 'eu-north-6' | 'eu-north-7' | 'eu-north-8' | 'eu-north-9' | 'ca-west-1' | 'ca-east-1' | 'us-central-3' | 'us-southeast-1' | 'me-central-1' | 'ca-east-2' | 'eu-west-1' | 'us-southeast-2' | 'jp-east-1' | 'us-southeast-3' | 'eu-west-5' | 'jp-east-2' | 'us-east-3' | 'uk-central-3' | 'uk-southeast-3' | 'eu-southwest-3' | 'eu-southwest-3-1' | 'eu-west-3' | 'eu-west-4' | 'private-cloud', required
  - `gpuType` 'h100' | 'h200' | 'b200' | 'rtx-6000-pro', required
  - `gpuCount` integer, required
  - `gpuFormFactor` 'sxm5' | 'sxm6' | 'pcie', required
  - `connectionType` 'infiniband' | 'ethernet', required
  - `ethernetVariant` 'normal' | 'rocev2', nullable, required
  - `nodes` RentalNode[], required
    - `cpuModel` string, required
    - `cpuCount` number, nullable, required
    - `vcpuCount` number, nullable, required
    - `gpuCount` number, required
    - `ramGb` number, required
    - `storageGb` number, required
  - `sshEndpoints` SshEndpoint[], required
    - `host` string, required
    - `port` number, required
    - `user` string, required
  - `networkInterfaces` NetworkInterface[], required
    - `publicIp` string, required
    - `privateIp` string, required
  - `portMappings` PortMapping[], required
    - `externalPort` number, required
    - `internalPort` number, required
  - `supportsPortForwarding` boolean, required
  - `exposedPorts` number[], required
  - `supportsCustomPorts` boolean, required
  - `supportsMultipleSshKeys` boolean, required
  - `supportsSshKeyUpdates` boolean, required
  - `attachedStorage` AttachedStorage[], required
    - `storageVolumeId` string, required
    - `label` string, required
    - `sizeInGb` integer, required
    - `virtualIp` string, required
    - `costPerHourCents` number, required
  - `supportsAttachedStorage` boolean, required
  - `monitoringEnabled` boolean, required
  - `convertToOnDemandOnExpiry` boolean, nullable, required
  - `terminationReason` string, nullable, required
  - `currentTerm` union, required
    - object
      - `effectiveAt` string, date-time, required
      - `termType` 'on-demand', required
      - `costPerHour` number, required
      - `reservedUntil` unknown, required
      - `reservationEndsAt` unknown, required
      - `termPeriodDays` unknown, required
      - `discountPercentage` unknown, required
      - `originalCostPerHour` unknown, required
    - object
      - `effectiveAt` string, date-time, required
      - `termType` 'reserved', required
      - `costPerHour` number, required
      - `reservedUntil` string, date-time, nullable, required
      - `reservationEndsAt` string, date-time, nullable, required
      - `termPeriodDays` number, required
      - `discountPercentage` number, required
      - `originalCostPerHour` number, required
    - object
      - `effectiveAt` string, date-time, required
      - `termType` 'private-cloud', required
      - `costPerHour` number, required
      - `reservedUntil` unknown, required
      - `reservationEndsAt` unknown, required
      - `termPeriodDays` unknown, required
      - `discountPercentage` unknown, required
      - `originalCostPerHour` unknown, required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, nullable, required
  - `startedAt` string, date-time, nullable, required
  - `terminatedAt` string, date-time, nullable, required
  - `userId` string, required
  - `orgId` string, nullable, required
  - `createdBy` RentalCreator, required: The user who created a rental.
    - `id` string, required
    - `name` string, nullable, required
    - `email` string, required
    - `picture` string, nullable, required
  - `privateCluster` PrivateCluster, required: The topology of a dedicated private cluster.
    - `gpuModel` string, nullable, required
    - `location` string, nullable, required
    - `sshUser` string, required
    - `sshPort` number, nullable, required
    - `nodes` PrivateClusterNode[], required
      - `role` 'login' | 'head' | 'compute', required
      - `hostname` string, nullable, required
      - `publicIp` string, nullable, required
      - `privateIp` string, required
    - `handover` object, required
  - `managedCluster` ManagedClusterRef, required: The managed Kubernetes cluster a rental is a node pool of.
    - `name` string, required
    - `label` string, nullable, required

## Other responses

- `400`: Invalid input data
- `401`: Authorization not provided
- `403`: Insufficient access
- `500`: Internal server error

## Changes

- **2026-11-04** `ebe33157e243`: 1 breaking
  - the `termPeriodDays` request property's max was decreased to `30.00`
- **2026-10-31** `194666d30bfc`: 1 warning, 1 info
  - added the new `jp-east-2` enum value to the `region` response property for the response status `200`
  - added the new `jp-east-2` enum value to the request property `region/anyOf[subschema #1]/`
- **2026-10-27** `dbf29b4ec8ea`: 1 info
  - added the new optional request property `monitoringOptOut`
- **2026-10-26** `6d718ca26d2b`: 15 breaking, 15 info
  - the response property `convertToOnDemandOnExpiry` became nullable for the status `200`
  - the response property `createdBy/name` became nullable for the status `200`
  - the response property `createdBy/picture` became nullable for the status `200`
  - the response property `label` became nullable for the status `200`
  - …26 more
- **2026-10-21** `ae69ee1b2989`: 2 info
  - added the required property `supportsMultipleSshKeys` to the response with the `200` status
  - added the required property `supportsSshKeyUpdates` to the response with the `200` status

[Operation history](https://skmtc.dev/hyperbolic/apis/castle-api/changes/v2/on-demand/rentals/post.md)

---

[API](https://skmtc.dev/hyperbolic/apis/castle-api.md) - [All operations](https://skmtc.dev/hyperbolic/apis/castle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hyperbolic/apis/castle-api/revisions/d4d4f25214b8?raw)