Servers

The Servers API covers the full rental lifecycle: browsing the marketplace, reserving ordered machines, managing active rentals, and organizing servers into team pools. Use these endpoints to list available servers, rent or extend a server, monitor runtime metrics, and manage pool membership.

All endpoints are scoped to the control plane at https://api.hoody.com and require a valid JWT token in the Authorization header.

Marketplace

Browse machines available for immediate rental and machines that can be ordered with a delivery lead time.

`GET /api/v1/offers`

Browse machines available to order. These are servers that are not in stock but can be reserved with a delivery lead time (1..720 hours).

curl -X GET "https://api.hoody.com/api/v1/offers" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.serverRental.listServerOffers();

{
  "statusCode": 200,
  "message": "Offers retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439050",
      "name": "node-eu-fra-2",
      "country": "DE",
      "region": "eu-central",
      "city": "Frankfurt",
      "datacenter": "FRA-DC2",
      "cpu_model": "AMD EPYC 7763",
      "cpu_cores": 64,
      "cpu_threads": 128,
      "ram_gb": 256,
      "disks": [
        { "count": 2, "capacity_gb": 1000, "type": "NVMe" },
        { "count": 6, "capacity_gb": 15000, "type": "NVMe" }
      ],
      "bandwidth_mbps": 10000,
      "traffic_tb": 100,
      "traffic_unlimited": false,
      "ipv4_count": 5,
      "pricing_rules": { "30": 25000, "90": 70000 },
      "hold_rules": { "30": 2, "90": 3 },
      "setup_fee_cents": 2500,
      "setup_fee_rules": { "30": 2500, "90": 0 },
      "delivery_hours": 48,
      "setup_time_minutes": 30,
      "stock": 12
    }
  ]
}

`GET /api/v1/servers/available`

Browse the rental marketplace and filter available in-stock servers.

Parameters

Name	In	Type	Required	Description
`country`	query	string	No	Filter by country code (e.g., US, DE)
`region`	query	string	No	Filter by region (e.g., us-east, eu-central)
`max_price_per_day`	query	number	No	Maximum price per day in USD
`available_durations`	query	array	No	Filter servers that support these rental durations (days)
`min_cpu_cores`	query	number	No	Minimum CPU cores
`min_cpu_score`	query	number	No	Minimum CPU benchmark score
`cpu_score_type`	query	string	No	CPU benchmark type for score filtering. One of `passmark`, `geekbench_single`, `geekbench_multi`
`min_ram_gb`	query	number	No	Minimum RAM in GB
`ram_types`	query	array	No	Filter by RAM types
`min_total_storage_gb`	query	number	No	Minimum total storage in GB
`disk_types`	query	array	No	Filter servers with these disk types
`min_bandwidth_mbps`	query	number	No	Minimum network bandwidth in Mbps
`min_traffic_tb`	query	number	No	Minimum monthly traffic allowance in TB
`unlimited_traffic_only`	query	boolean	No	Show only servers with unlimited traffic
`category`	query	string	No	Filter by server category. One of `compute`, `memory`, `storage`, `general`, `gpu`
`featured_only`	query	boolean	No	Show only featured servers

curl -X GET "https://api.hoody.com/api/v1/servers/available?country=US&min_cpu_cores=32&featured_only=true" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.serverRental.browseIterator({ country: 'US', min_cpu_cores: 32, featured_only: true });

{
  "statusCode": 200,
  "message": "Available servers retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439014",
      "name": "node-us-nyc-1",
      "country": "US",
      "region": "us-east",
      "city": "New York",
      "datacenter": "NYC-DC1",
      "model": "Intel Xeon E5-2680 v4",
      "is_vm": false,
      "category": "compute",
      "featured": true,
      "popularity_rank": 1,
      "setup_time_minutes": 15,
      "delivery_hours": 0,
      "pricing": {
        "prices": { "1": "12.00", "7": "70.00", "30": "250.00" },
        "setup_fee": "25.00",
        "setup_fee_cents": 2500,
        "price_tiers": {
          "1": { "price": "12.00", "hold_days": 1, "total_first_payment": "37.00" },
          "7": { "price": "70.00", "hold_days": 2, "total_first_payment": "95.00" },
          "30": { "price": "250.00", "hold_days": 5, "total_first_payment": "275.00" }
        }
      },
      "specs": {
        "cpu": {
          "model": "AMD EPYC 7763",
          "cores": 64,
          "threads": 128,
          "score": 48500,
          "score_type": "passmark"
        },
        "ram": { "capacity_gb": 256, "type": "ECC DDR5", "speed_mhz": 4800 },
        "disks": {
          "config": [
            { "count": 2, "capacity_gb": 1000, "type": "NVMe", "interface": "PCIe 4.0" },
            { "count": 6, "capacity_gb": 15000, "type": "NVMe", "interface": "PCIe 4.0" }
          ],
          "total_gb": 92000,
          "summary": "2x1TB NVMe + 6x15TB NVMe"
        },
        "network": {
          "bandwidth_mbps": 10000,
          "bandwidth_formatted": "10 Gbps",
          "traffic_tb": 100,
          "traffic_unlimited": false
        },
        "additional": { "ipv4_count": 5, "ipv6_enabled": true }
      }
    }
  ]
}

Reservations

Manage reservations against offers (machines not in stock but orderable with a lead time).

`GET /api/v1/reservations`

List your reservations.

Parameters

Name	In	Type	Required	Description
`limit`	query	integer	No	Maximum number of results to return. Default: `50`
`offset`	query	integer	No	Number of results to skip. Default: `0`

curl -X GET "https://api.hoody.com/api/v1/reservations?limit=20&offset=0" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.serverRental.listMyReservations({ limit: 20, offset: 0 });

{
  "statusCode": 200,
  "message": "Reservations retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439400",
      "offer_id": "507f1f77bcf86cd799439050",
      "days": 30,
      "state": "pending",
      "ready_by": "2025-02-15T22:00:00.000Z",
      "delivery_hours_quoted": 48,
      "setup_time_minutes_quoted": 30,
      "hold_days_quoted": 2,
      "server_id": null,
      "rental_id": null,
      "created_at": "2025-01-21T22:00:00.000Z",
      "rental_cents": 25000,
      "setup_fee_cents": 2500,
      "total_paid_cents": 27500,
      "offer_snapshot": {
        "name": "node-eu-fra-2",
        "country": "DE",
        "cpu_cores": 64
      }
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

`GET /api/v1/reservations/{id}`

Retrieve a single reservation by ID.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Reservation ID

curl -X GET "https://api.hoody.com/api/v1/reservations/507f1f77bcf86cd799439400" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.serverRental.getMyReservation('507f1f77bcf86cd799439400');

{
  "statusCode": 200,
  "message": "Reservation retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439400",
    "offer_id": "507f1f77bcf86cd799439050",
    "days": 30,
    "state": "pending",
    "ready_by": "2025-02-15T22:00:00.000Z",
    "delivery_hours_quoted": 48,
    "setup_time_minutes_quoted": 30,
    "hold_days_quoted": 2,
    "server_id": null,
    "rental_id": null,
    "created_at": "2025-01-21T22:00:00.000Z",
    "rental_cents": 25000,
    "setup_fee_cents": 2500,
    "total_paid_cents": 27500,
    "offer_snapshot": { "name": "node-eu-fra-2", "country": "DE" }
  }
}

`POST /api/v1/offers/{id}/reserve`

Reserve an offer. Charges immediately.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Offer ID

Request Body

Name	Type	Required	Description
`days`	number	Yes	Must be one of the offer’s pricing_rules keys.
`max_charge_cents`	number	No	Ceiling on the TOTAL debit (rent + any one-time setup fee). REQUIRED for every paid reservation, not only ones carrying a setup fee. Compute it as `pricing_rules[days]` plus `setup_fee_rules[days]` when that key is present, else `setup_fee_cents`. A present override wins even when it is 0. If you get a 409, that error’s `data` carries the authoritative `total_cents` for the duration you asked for.
`idempotency_key`	string	Yes	Caller-generated. Replaying it returns the original reservation, unpaid twice.
`pool_id`	string	No	Must be a pool you own. Defaults to your default pool.

curl -X POST "https://api.hoody.com/api/v1/offers/507f1f77bcf86cd799439050/reserve" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "days": 30,
    "max_charge_cents": 27500,
    "idempotency_key": "reserve-2025-01-21-abc123",
    "pool_id": "507f1f77bcf86cd799439300"
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.serverRental.reserveServerOffer('507f1f77bcf86cd799439050', {
  days: 30,
  max_charge_cents: 27500,
  idempotency_key: 'reserve-2025-01-21-abc123',
  pool_id: '507f1f77bcf86cd799439300'
});

{
  "statusCode": 201,
  "message": "Reservation created successfully",
  "data": {
    "reservation": {
      "id": "507f1f77bcf86cd799439400",
      "offer_id": "507f1f77bcf86cd799439050",
      "days": 30,
      "state": "pending",
      "ready_by": "2025-02-15T22:00:00.000Z",
      "delivery_hours_quoted": 48,
      "setup_time_minutes_quoted": 30,
      "hold_days_quoted": 2,
      "server_id": null,
      "rental_id": null,
      "created_at": "2025-01-21T22:00:00.000Z",
      "rental_cents": 25000,
      "setup_fee_cents": 2500,
      "total_paid_cents": 27500,
      "offer_snapshot": { "name": "node-eu-fra-2", "country": "DE" }
    },
    "replayed": false
  }
}

{
  "statusCode": 409,
  "error": "OUT_OF_STOCK",
  "message": "This offer is out of stock."
}

Error Code	Title	Description	Resolution
`OFFER_UNAVAILABLE`	Offer has been withdrawn	The listing is no longer active because it was withdrawn. Withdrawing an offer never affects reservations that were already placed against it.	Re-read GET /api/v1/offers and present what is currently purchasable.
`OUT_OF_STOCK`	Offer is sold out	Stock is exhausted. Also returned when another customer took the last unit a moment earlier — nothing was charged.	Re-read GET /api/v1/offers; the offer may return to stock later.
`IDEMPOTENCY_INTENT_MISMATCH`	Idempotency key reused for a different purchase	The supplied idempotency_key was already used for a reservation with different terms. Returning the original would silently give the caller something other than what this request asked for, so it fails instead.	Use a fresh idempotency_key for a genuinely new purchase.
`SETUP_FEE_CONFIRMATION_REQUIRED`	One-time setup fee must be confirmed	This machine carries a one-time setup fee. The request omitted max_charge_cents, so the total was never confirmed and nothing was charged.	Read the totals in this error’s `data`, show them to the customer, then retry with max_charge_cents set to data.total_cents. Do not compute the total yourself.
`CHARGE_CONFIRMATION_REQUIRED`	The total must be confirmed before money moves	The request would debit an account and carried no max_charge_cents. Nothing was charged. Applies to every paid purchase, including servers with no one-time setup fee.	Read the current total, show it to the customer, and retry with max_charge_cents set to the value they confirmed. Never auto-retry with the total from this error.
`CHARGE_EXCEEDS_MAX`	Price changed since the quote	The live total is higher than the max_charge_cents ceiling supplied with the request, so nothing was charged.	Re-read the listing, show the user the new total, and retry with an updated max_charge_cents once they confirm. Do NOT auto-retry with the returned actual value.

{
  "statusCode": 500,
  "error": "PRICING_INVALID",
  "message": "Server pricing is misconfigured and cannot be charged. Please contact support."
}

Error Code	Title	Description	Resolution
`PRICING_INVALID`	Stored pricing is misconfigured	The server’s stored pricing did not pass validation when the charge was attempted. The request fails closed and nothing is charged.	This server cannot be rented until its pricing is corrected. Please contact support. Retrying beforehand cannot succeed.

Rentals

Manage active and historical rentals.

`GET /api/v1/rentals`

List all rentals for the authenticated user.

curl -X GET "https://api.hoody.com/api/v1/rentals" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.rentals.listIterator();

{
  "statusCode": 200,
  "message": "Rentals retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439320",
      "rental_start": "2025-01-21T22:00:00.000Z",
      "rental_end": "2025-01-28T22:00:00.000Z",
      "status": "active",
      "amount": "70.00",
      "setup_fee_cents": 2500,
      "total_paid_cents": 9500,
      "renewal_pricing_frozen": { "30": 8000 },
      "remaining_days": 6,
      "server_id": "507f1f77bcf86cd799439014",
      "pool_id": "507f1f77bcf86cd799439300",
      "is_free_tier": false,
      "server": {
        "container_capacity": { "used": 3, "max": 10 },
        "id": "507f1f77bcf86cd799439014",
        "name": "node-us-nyc-1",
        "country": "US",
        "region": "us-east",
        "city": "New York",
        "datacenter": "NYC-DC1",
        "model": "Intel Xeon E5-2680 v4",
        "is_vm": false,
        "specs": {
          "cpu": {
            "model": "AMD EPYC 7763",
            "cores": 64,
            "threads": 128,
            "score": 48500,
            "score_type": "passmark"
          },
          "ram": { "capacity_gb": 256, "type": "ECC DDR5", "speed_mhz": 4800 },
          "disks": {
            "config": [
              { "count": 2, "capacity_gb": 1000, "type": "NVMe", "interface": "PCIe 4.0" }
            ],
            "total_gb": 2000,
            "summary": "2x1TB NVMe"
          },
          "network": {
            "bandwidth_mbps": 10000,
            "bandwidth_formatted": "10 Gbps",
            "traffic_tb": 100,
            "traffic_unlimited": false
          },
          "additional": { "ipv4_count": 5, "ipv6_enabled": true }
        }
      }
    }
  ]
}

`GET /api/v1/rentals/{id}`

Retrieve detailed information about a specific rental.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Rental ID

curl -X GET "https://api.hoody.com/api/v1/rentals/507f1f77bcf86cd799439320" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.rentals.get('507f1f77bcf86cd799439320');

{
  "statusCode": 200,
  "message": "Rental retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439320",
    "rental_start": "2025-01-21T22:00:00.000Z",
    "rental_end": "2025-01-28T22:00:00.000Z",
    "hold_days": 2,
    "status": "active",
    "amount": "70.00",
    "setup_fee_cents": 2500,
    "total_paid_cents": 9500,
    "renewal_pricing_frozen": { "30": 8000 },
    "remaining_days": 6,
    "usage_days": 1,
    "server_id": "507f1f77bcf86cd799439014",
    "pool_id": "507f1f77bcf86cd799439300",
    "is_free_tier": false,
    "server": {
      "id": "507f1f77bcf86cd799439014",
      "name": "node-us-nyc-1",
      "country": "US",
      "region": "us-east",
      "city": "New York",
      "datacenter": "NYC-DC1",
      "model": "Intel Xeon E5-2680 v4",
      "is_vm": false,
      "specs": {
        "cpu": {
          "model": "AMD EPYC 7763",
          "cores": 64,
          "threads": 128,
          "score": 48500,
          "score_type": "passmark"
        },
        "ram": { "capacity_gb": 256, "type": "ECC DDR5", "speed_mhz": 4800 },
        "disks": {
          "config": [
            { "count": 2, "capacity_gb": 1000, "type": "NVMe", "interface": "PCIe 4.0" },
            { "count": 6, "capacity_gb": 15000, "type": "NVMe", "interface": "PCIe 4.0" }
          ],
          "total_gb": 92000,
          "summary": "2x1TB NVMe + 6x15TB NVMe"
        },
        "network": {
          "bandwidth_mbps": 10000,
          "bandwidth_formatted": "10 Gbps",
          "traffic_tb": 100,
          "traffic_unlimited": false
        },
        "additional": { "ipv4_count": 5, "ipv6_enabled": true }
      }
    },
    "transaction": {
      "id": "507f1f77bcf86cd799439321",
      "amount": 70,
      "currency": "USD",
      "created_at": "2025-01-21T22:00:00.000Z"
    }
  }
}

`GET /api/v1/rentals/{id}/runtime`

Get live CPU/memory/disk usage for a rented server or subserver. Served from a short-TTL cache so it can be polled frequently. First-party JWT only. Physical scope requires the server to have no subservers; a shared or system host returns 409. Subserver scope may be disabled on this deployment.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Rental ID

curl -X GET "https://api.hoody.com/api/v1/rentals/507f1f77bcf86cd799439320/runtime" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.serverRental.getRentalRuntime('507f1f77bcf86cd799439320');

{
  "statusCode": 200,
  "message": "Runtime info retrieved successfully",
  "data": {
    "scope": "server",
    "ts": "2025-01-22T10:30:00.000Z",
    "cache_age_ms": 1500,
    "stale": false,
    "uptime_s": 45000,
    "cores": 64,
    "load": { "1": 1.2, "5": 0.9, "15": 0.7 },
    "cpu": { "busy_pct": 12.4 },
    "mem": { "used_bytes": 8589934592, "total_bytes": 274877906944, "pct": 3.1 },
    "swap": { "used_bytes": 0, "total_bytes": 8589934592 },
    "storage": { "used_bytes": 123456789012, "total_bytes": 98784247808000, "pct": 0.1 }
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}

Error Code	Title	Description	Resolution
`INVALID_ID_FORMAT`	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as `Bearer <token>`
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
`INSUFFICIENT_PERMISSIONS`	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Error Code	Title	Description	Resolution
`RESOURCE_NOT_FOUND`	Resource not found	The requested resource does not exist or has been deleted	Verify the resource ID and ensure it exists

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Host runtime not available for a shared server"
}

Error Code	Title	Description	Resolution
`RUNTIME_HOST_SHARED`	Host runtime not available for a shared server	Host-level runtime info is not exposed for a physical server that hosts subservers or is a system server, because it would reveal co-tenant activity.	Query runtime for the specific subserver you rent instead of the whole physical host.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

Error Code	Title	Description	Resolution
`RATE_LIMIT_EXCEEDED`	Rate limit exceeded	You have exceeded the rate limit for this endpoint	Wait before making additional requests, or upgrade your plan for higher limits

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Runtime info temporarily unavailable"
}

Error Code	Title	Description	Resolution
`RUNTIME_UNAVAILABLE`	Runtime info temporarily unavailable	Live runtime info could not be collected for this server and no recent snapshot is available.	Retry shortly. If it persists, the host may be unreachable or under maintenance.

`POST /api/v1/rentals/{id}/extend`

Extend an existing rental for additional days.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Rental ID

Request Body

Name	Type	Required	Description
`expected_rental_end`	string	Yes	The rental’s CURRENT rental_end, exactly as the API returned it. The extension is applied only if it still matches, so a retried request is refused with 409 `EXTENSION_ALREADY_APPLIED` instead of charging and extending a second time. Re-read the rental before retrying; never resend blindly.
`additional_days`	integer	Yes	Number of additional days to extend the rental (must match server pricing durations, max 3650).
`max_charge_cents`	integer	No	The total you confirmed, in whole cents. The extension is refused if it would cost more. REQUIRED when the rental has no frozen renewal price (409 `CHARGE_CONFIRMATION_REQUIRED`). Optional when the rental still carries frozen tiers, which are themselves a ceiling.

curl -X POST "https://api.hoody.com/api/v1/rentals/507f1f77bcf86cd799439320/extend" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_rental_end": "2025-01-28T22:00:00.000Z",
    "additional_days": 7,
    "max_charge_cents": 7000
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.rentals.extend('507f1f77bcf86cd799439320', {
  expected_rental_end: '2025-01-28T22:00:00.000Z',
  additional_days: 7,
  max_charge_cents: 7000
});

{
  "statusCode": 200,
  "message": "Rental extended successfully",
  "data": {
    "rental": {
      "id": "507f1f77bcf86cd799439320",
      "rental_end": "2025-02-04T22:00:00.000Z",
      "status": "active",
      "amount": "140.00",
      "setup_fee_cents": 2500,
      "total_paid_cents": 16500,
      "renewal_pricing_frozen": { "30": 8000 },
      "remaining_days": 13
    },
    "transaction": {
      "id": "507f1f77bcf86cd799439322",
      "amount": 70,
      "currency": "USD"
    }
  }
}

{
  "statusCode": 409,
  "error": "EXTENSION_ALREADY_APPLIED",
  "message": "This rental has already been extended. Re-read it and confirm the new total before extending again.",
  "data": {
    "rental_id": "507f1f77bcf86cd799439320",
    "rental_end": "2026-09-01T00:00:00.000Z",
    "expected_rental_end": "2026-08-01T00:00:00.000Z"
  }
}

Error Code	Title	Description	Resolution
`EXTENSION_ALREADY_APPLIED`	That extension has already been applied	The rental’s end date no longer matches the expected_rental_end sent with the request, so the extension was not applied again. Nothing was charged.	Re-read the rental. If its end date already reflects the extension you wanted, you are done. Otherwise retry with expected_rental_end set to the value you just read. Never retry with the original value.
`CHARGE_CONFIRMATION_REQUIRED`	The total must be confirmed before money moves	The request would debit an account and carried no max_charge_cents. Nothing was charged.	Read the current total, show it to the customer, and retry with max_charge_cents set to the value they confirmed. Never auto-retry with the total from this error.
`CHARGE_EXCEEDS_MAX`	Price changed since the quote	The live total is higher than the max_charge_cents ceiling supplied with the request, so nothing was charged.	Re-read the listing, show the user the new total, and retry with an updated max_charge_cents once they confirm. Do NOT auto-retry with the returned actual value.

Servers (aliases)

/api/v1/servers and /api/v1/servers/{id} are aliases for the rentals endpoints and return the same data.

`GET /api/v1/servers`

List all rented servers for the authenticated user. Alias for GET /api/v1/rentals.

curl -X GET "https://api.hoody.com/api/v1/servers" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.serverRental.listIterator();

{
  "statusCode": 200,
  "message": "Rentals retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439320",
      "rental_start": "2025-01-21T22:00:00.000Z",
      "rental_end": "2025-01-28T22:00:00.000Z",
      "status": "active",
      "amount": "70.00",
      "remaining_days": 6,
      "server_id": "507f1f77bcf86cd799439014",
      "pool_id": "507f1f77bcf86cd799439300",
      "server": { "id": "507f1f77bcf86cd799439014" }
    }
  ]
}

`GET /api/v1/servers/{id}`

Retrieve detailed information about a specific rented server. Alias for GET /api/v1/rentals/{id}.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Server/Rental ID

curl -X GET "https://api.hoody.com/api/v1/servers/507f1f77bcf86cd799439320" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.serverRental.get('507f1f77bcf86cd799439320');

{
  "statusCode": 200,
  "message": "Rental details retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439320",
    "rental_start": "2025-01-21T22:00:00.000Z",
    "rental_end": "2025-01-28T22:00:00.000Z",
    "hold_days": 2,
    "status": "active",
    "amount": "70.00",
    "setup_fee_cents": 2500,
    "total_paid_cents": 9500,
    "renewal_pricing_frozen": { "30": 8000 },
    "remaining_days": 6,
    "usage_days": 1,
    "server_id": "507f1f77bcf86cd799439014",
    "pool_id": "507f1f77bcf86cd799439300",
    "is_free_tier": false,
    "server": {
      "id": "507f1f77bcf86cd799439014",
      "name": "node-us-nyc-1",
      "country": "US",
      "region": "us-east",
      "city": "New York",
      "datacenter": "NYC-DC1",
      "model": "Intel Xeon E5-2680 v4",
      "is_vm": false,
      "specs": {
        "cpu": {
          "model": "AMD EPYC 7763",
          "cores": 64,
          "threads": 128,
          "score": 48500,
          "score_type": "passmark"
        },
        "ram": { "capacity_gb": 256, "type": "ECC DDR5", "speed_mhz": 4800 },
        "disks": {
          "config": [
            { "count": 2, "capacity_gb": 1000, "type": "NVMe", "interface": "PCIe 4.0" }
          ],
          "total_gb": 2000,
          "summary": "2x1TB NVMe"
        },
        "network": {
          "bandwidth_mbps": 10000,
          "bandwidth_formatted": "10 Gbps",
          "traffic_tb": 100,
          "traffic_unlimited": false
        },
        "additional": { "ipv4_count": 5, "ipv6_enabled": true }
      }
    },
    "transaction": {
      "id": "507f1f77bcf86cd799439321",
      "amount": 70,
      "currency": "USD",
      "created_at": "2025-01-21T22:00:00.000Z"
    }
  }
}

`GET /api/v1/servers/{id}/runtime`

Live CPU/memory/disk usage for a rented server. Alias for GET /api/v1/rentals/{id}/runtime.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Server/Rental ID

curl -X GET "https://api.hoody.com/api/v1/servers/507f1f77bcf86cd799439320/runtime" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.serverRental.getServerRuntime('507f1f77bcf86cd799439320');

{
  "statusCode": 200,
  "message": "Runtime info retrieved successfully",
  "data": {
    "scope": "subserver",
    "ts": "2025-01-22T10:30:00.000Z",
    "cache_age_ms": 800,
    "stale": false,
    "health": "ok",
    "cpu": { "usage_cores": 0.5, "usage_pct": 4.2, "limit_cores": 12 },
    "mem": { "used_bytes": 2147483648, "limit_bytes": 34359738368, "pct": 6.2 },
    "disk": { "used_bytes": 5368709120, "limit_bytes": 536870912000, "pct": 1.0 },
    "pids": { "current": 42, "max": 512 },
    "io": { "read_bytes": 1073741824, "write_bytes": 536870912 }
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}

Error Code	Title	Description	Resolution
`INVALID_ID_FORMAT`	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as `Bearer <token>`
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
`INSUFFICIENT_PERMISSIONS`	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Resource not found"
}

Error Code	Title	Description	Resolution
`RESOURCE_NOT_FOUND`	Resource not found	The requested resource does not exist or has been deleted	Verify the resource ID and ensure it exists

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Host runtime not available for a shared server"
}

Error Code	Title	Description	Resolution
`RUNTIME_HOST_SHARED`	Host runtime not available for a shared server	Host-level runtime info is not exposed for a physical server that hosts subservers or is a system server, because it would reveal co-tenant activity.	Query runtime for the specific subserver you rent instead of the whole physical host.

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

Error Code	Title	Description	Resolution
`RATE_LIMIT_EXCEEDED`	Rate limit exceeded	You have exceeded the rate limit for this endpoint	Wait before making additional requests, or upgrade your plan for higher limits

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Runtime info temporarily unavailable"
}

Error Code	Title	Description	Resolution
`RUNTIME_UNAVAILABLE`	Runtime info temporarily unavailable	Live runtime info could not be collected for this server and no recent snapshot is available.	Retry shortly. If it persists, the host may be unreachable or under maintenance.

`POST /api/v1/servers/{id}/rent`

Rent an available in-stock server for a specified duration. Some servers carry a one-time setup fee charged only on this first payment (never on extension); when they do, the request must confirm the total via max_charge_cents.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Server ID

Request Body

Name	Type	Required	Description
`pool_id`	string	No	Pool ID (24-character hex).
`rental_days`	integer	Yes	Number of days to rent (must match server pricing durations, max 3650).
`max_charge_cents`	integer	No	Ceiling on the TOTAL debit (rental price + one-time setup fee), in integer cents. REQUIRED for every paid rental. Omitting it returns 409 `CHARGE_CONFIRMATION_REQUIRED`, or 409 `SETUP_FEE_CONFIRMATION_REQUIRED` when the server also carries a one-time fee. Only a total of zero needs no ceiling. If the live total exceeds this ceiling the request is rejected with 409 `CHARGE_EXCEEDS_MAX`. A ceiling (not an exact match) so a price DROP still succeeds. Read it from `pricing.price_tiers[rental_days].total_first_payment`.

curl -X POST "https://api.hoody.com/api/v1/servers/507f1f77bcf86cd799439014/rent" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pool_id": "507f1f77bcf86cd799439300",
    "rental_days": 7,
    "max_charge_cents": 9500
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.serverRental.rent('507f1f77bcf86cd799439014', {
  pool_id: '507f1f77bcf86cd799439300',
  rental_days: 7,
  max_charge_cents: 9500
});

{
  "statusCode": 201,
  "message": "Server rented successfully",
  "data": {
    "rental": {
      "id": "507f1f77bcf86cd799439320",
      "server_id": "507f1f77bcf86cd799439014",
      "rental_start": "2025-01-21T22:00:00.000Z",
      "rental_end": "2025-01-28T22:00:00.000Z",
      "hold_days": 2,
      "actual_usage_days": 0,
      "status": "active",
      "setup_fee_cents": 2500,
      "total_paid_cents": 9500,
      "renewal_pricing_frozen": { "30": 8000 }
    },
    "transaction": {
      "id": "507f1f77bcf86cd799439321",
      "amount": 95,
      "currency": "USD"
    }
  }
}

{
  "statusCode": 400,
  "error": "INSUFFICIENT_BALANCE",
  "message": "Insufficient balance for rental",
  "data": {
    "rental_cents": 7000,
    "setup_fee_cents": 2500,
    "required_cents": 9500,
    "available_cents": 5000
  }
}

Error Code	Title	Description	Resolution
`INSUFFICIENT_BALANCE`	Wallet balance too low	The wallet balance is below the total required for this rental. The response `data` breaks the total down into rental_cents, setup_fee_cents, required_cents and available_cents.	Top up the wallet to at least required_cents, then retry.
`INVALID_DURATION`	Rental duration not offered	rental_days must match a duration the server actually prices. There is no interpolation: 5 days is unrentable unless a “5” tier exists.	Pick one of pricing.available_durations and retry.
`NO_PRICING`	Server has no pricing configured	The server has no pricing row, or none covering the requested duration.	Choose a different server, or contact support to have pricing configured for it.

{
  "statusCode": 409,
  "error": "SERVER_UNAVAILABLE",
  "message": "Server not available for rental"
}

Error Code	Title	Description	Resolution
`SERVER_UNAVAILABLE`	Server not available for rental	The server is not rentable: it is already rented, not ready, or not offered for rental. Also returned when a concurrent request won the race for it.	Re-read GET /api/v1/servers/available and pick a currently available server.
`SETUP_FEE_CONFIRMATION_REQUIRED`	One-time setup fee must be confirmed	This machine carries a one-time setup fee. The request omitted max_charge_cents, so the total was never confirmed and nothing was charged.	Read the totals in this error’s `data`, show them to the customer, then retry with max_charge_cents set to data.total_cents. Do not compute the total yourself.
`CHARGE_CONFIRMATION_REQUIRED`	The total must be confirmed before money moves	The request would debit an account and carried no max_charge_cents. Nothing was charged. Applies to every paid purchase, including servers with no one-time setup fee.	Read the current total, show it to the customer, and retry with max_charge_cents set to the value they confirmed. Never auto-retry with the total from this error.
`CHARGE_EXCEEDS_MAX`	Price changed since the quote	The live total is higher than the max_charge_cents ceiling supplied with the request, so nothing was charged.	Re-read the listing, show the user the new total, and retry with an updated max_charge_cents once they confirm. Do NOT auto-retry with the returned actual value.

{
  "statusCode": 500,
  "error": "PRICING_INVALID",
  "message": "Server pricing is misconfigured and cannot be charged. Please contact support."
}

Error Code	Title	Description	Resolution
`PRICING_INVALID`	Stored pricing is misconfigured	The server’s stored pricing did not pass validation when the charge was attempted. The request fails closed and nothing is charged.	This server cannot be rented until its pricing is corrected. Please contact support. Retrying beforehand cannot succeed.

Pools

Organize servers and team members into shared pools.

`GET /api/v1/pools`

List all pools the authenticated user owns or is a member of.

curl -X GET "https://api.hoody.com/api/v1/pools" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.pools.listIterator();

{
  "statusCode": 200,
  "message": "Pools retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439300",
      "name": "Development Team",
      "description": "Pool for development team resources",
      "is_default": false,
      "settings": { "auto_approve": false, "max_servers": 10 },
      "created_at": "2025-01-15T10:00:00.000Z",
      "updated_at": "2025-01-20T14:30:00.000Z",
      "owner_id": "507f1f77bcf86cd799439011",
      "user_role": "owner",
      "member_count": 5,
      "server_count": 3
    }
  ]
}

`GET /api/v1/pools/{id}`

Retrieve detailed information about a specific pool, including members and servers.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Pool ID

curl -X GET "https://api.hoody.com/api/v1/pools/507f1f77bcf86cd799439300" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.pools.get('507f1f77bcf86cd799439300');

{
  "statusCode": 200,
  "message": "Pool retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439300",
    "name": "Development Team",
    "description": "Pool for development team resources",
    "is_default": false,
    "settings": { "auto_approve": false, "max_servers": 10 },
    "created_at": "2025-01-15T10:00:00.000Z",
    "updated_at": "2025-01-20T14:30:00.000Z",
    "owner_id": "507f1f77bcf86cd799439011",
    "members": [
      {
        "id": "507f1f77bcf86cd799439310",
        "role": "admin",
        "is_authorized": true,
        "joined_at": "2025-01-16T11:00:00.000Z",
        "user": {
          "id": "507f1f77bcf86cd799439012",
          "username": "jane_admin",
          "alias": "Jane Smith"
        }
      }
    ],
    "servers": [
      {
        "id": "507f1f77bcf86cd799439014",
        "name": "node-us-nyc-1",
        "rental_status": "active",
        "is_ready": true
      }
    ]
  }
}

`POST /api/v1/pools`

Create a new pool for team collaboration.

Request Body

Name	Type	Required	Description
`name`	string	Yes	Pool name (max 100 characters).
`description`	string	No	Pool description (max 500 characters).
`settings`	object	No	Pool settings object.

curl -X POST "https://api.hoody.com/api/v1/pools" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Team",
    "description": "Pool for production environment management",
    "settings": { "auto_approve": true, "max_servers": 20 }
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.pools.create({
  name: 'Production Team',
  description: 'Pool for production environment management',
  settings: { auto_approve: true, max_servers: 20 }
});

{
  "statusCode": 201,
  "message": "Pool created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439301",
    "name": "Production Team",
    "description": "Pool for production environment management",
    "owner_id": "507f1f77bcf86cd799439011",
    "is_default": false,
    "settings": { "auto_approve": true, "max_servers": 20 },
    "created_at": "2025-01-21T22:00:00.000Z"
  }
}

`PUT /api/v1/pools/{id}`

Update pool details (owner only).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Pool ID

Request Body

Name	Type	Required	Description
`description`	string	No	Pool description (max 500 characters).
`settings`	object	No	Pool settings object.

curl -X PUT "https://api.hoody.com/api/v1/pools/507f1f77bcf86cd799439301" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated pool description",
    "settings": { "auto_approve": false, "max_servers": 25 }
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.pools.update('507f1f77bcf86cd799439301', {
  description: 'Updated pool description',
  settings: { auto_approve: false, max_servers: 25 }
});

{
  "statusCode": 200,
  "message": "Pool updated successfully",
  "data": { "success": true }
}

`DELETE /api/v1/pools/{id}`

Delete a pool (owner only, cannot delete default pool).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Pool ID

curl -X DELETE "https://api.hoody.com/api/v1/pools/507f1f77bcf86cd799439301" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.pools.delete('507f1f77bcf86cd799439301');

{
  "statusCode": 200,
  "message": "Pool deleted successfully",
  "data": { "success": true }
}

Pool Members

Invite, role-update, and remove members in a pool.

`POST /api/v1/pools/{id}/members`

Invite a user to join the pool (admin or owner only).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	id path parameter

Request Body

Name	Type	Required	Description
`username`	string	Yes	Username of the user to invite (1-100 chars, matches `^[a-zA-Z0-9_-]+$`).
`role`	string	Yes	Role to assign. One of `admin`, `user`.

curl -X POST "https://api.hoody.com/api/v1/pools/507f1f77bcf86cd799439300/members" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "new_member",
    "role": "user"
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.poolMembers.invite('507f1f77bcf86cd799439300', {
  username: 'new_member',
  role: 'user'
});

{
  "statusCode": 201,
  "message": "Member invited successfully",
  "data": {
    "id": "507f1f77bcf86cd799439311",
    "role": "user",
    "is_authorized": false,
    "invited_at": "2025-01-21T22:15:00.000Z"
  }
}

`PUT /api/v1/pools/{id}/members/{userId}`

Update a member’s role in the pool (owner only).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Pool ID
`userId`	path	string	Yes	User ID of the member

Request Body

Name	Type	Required	Description
`role`	string	Yes	New role. One of `admin`, `user`.

curl -X PUT "https://api.hoody.com/api/v1/pools/507f1f77bcf86cd799439300/members/507f1f77bcf86cd799439311" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.poolMembers.updateRole('507f1f77bcf86cd799439300', '507f1f77bcf86cd799439311', { role: 'admin' });

{
  "statusCode": 200,
  "message": "Member role updated successfully",
  "data": { "success": true }
}

`DELETE /api/v1/pools/{id}/members/{userId}`

Remove a member from the pool (admin or owner only).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Pool ID
`userId`	path	string	Yes	User ID of the member to remove

curl -X DELETE "https://api.hoody.com/api/v1/pools/507f1f77bcf86cd799439300/members/507f1f77bcf86cd799439311" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.poolMembers.remove('507f1f77bcf86cd799439300', '507f1f77bcf86cd799439311');

{
  "statusCode": 200,
  "message": "Member removed successfully",
  "data": { "success": true }
}

Pool Invitations

View and act on pool invitations.

`GET /api/v1/pools/invitations/pending`

List all pending pool invitations for the authenticated user.

curl -X GET "https://api.hoody.com/api/v1/pools/invitations/pending" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.poolInvitations.list();

{
  "statusCode": 200,
  "message": "Pending invitations retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439311",
      "pool_id": "507f1f77bcf86cd799439300",
      "pool_name": "Development Team",
      "pool_description": "Pool for development team resources",
      "role": "user",
      "invited_by": {
        "id": "507f1f77bcf86cd799439011",
        "username": "team_lead",
        "alias": "Team Lead"
      },
      "invited_at": "2025-01-21T22:15:00.000Z"
    }
  ]
}

`POST /api/v1/pools/{id}/accept`

Accept an invitation to join a pool.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Invitation ID

curl -X POST "https://api.hoody.com/api/v1/pools/507f1f77bcf86cd799439311/accept" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.poolInvitations.accept('507f1f77bcf86cd799439311');

{
  "statusCode": 200,
  "message": "Invitation accepted successfully",
  "data": { "success": true }
}

`POST /api/v1/pools/{id}/reject`

Reject an invitation to join a pool.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	id path parameter

curl -X POST "https://api.hoody.com/api/v1/pools/507f1f77bcf86cd799439311/reject" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.poolInvitations.reject('507f1f77bcf86cd799439311');

{
  "statusCode": 200,
  "message": "Invitation rejected successfully",
  "data": { "success": true }
}