Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Servers

Section titled “Servers”

The Servers API covers the full rental lifecycle: browsing the marketplace of in-stock servers and orderable offers, reserving or renting, extending, monitoring live runtime, and managing team pools, invitations, and membership. Use these endpoints when you want to programmatically provision dedicated hardware, manage who shares access via pools, or watch resource consumption on rented boxes. It also covers the paid subserver subscription program: monthly plans you can buy, pay, upgrade, cancel, and renew.

Marketplace

Section titled “Marketplace”

Browse in-stock servers and orderable offers. In-stock machines report delivery_hours: 0; offers carry a 1 to 720 hour lead time.

GET /api/v1/servers/available

Section titled “GET /api/v1/servers/available”

Browse the rental marketplace. Returns in-stock servers with full pricing tiers and specifications.

Terminal window
curl -X GET 'https://api.hoody.com/api/v1/servers/available?country=US&min_cpu_cores=8&min_ram_gb=32' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
countryquerystringNoFilter by country code (e.g., US, DE)
regionquerystringNoFilter by region (e.g., us-east, eu-central)
max_price_per_dayquerynumberNoMaximum price per day in USD
available_durationsqueryarrayNoFilter servers that support these rental durations (days)
min_cpu_coresquerynumberNoMinimum CPU cores
min_cpu_scorequerynumberNoMinimum CPU benchmark score
cpu_score_typequerystringNoCPU benchmark type for score filtering. Allowed: passmark, geekbench_single, geekbench_multi
min_ram_gbquerynumberNoMinimum RAM in GB
ram_typesqueryarrayNoFilter by RAM types
min_total_storage_gbquerynumberNoMinimum total storage in GB
disk_typesqueryarrayNoFilter servers with these disk types
min_bandwidth_mbpsquerynumberNoMinimum network bandwidth in Mbps
min_traffic_tbquerynumberNoMinimum monthly traffic allowance in TB
unlimited_traffic_onlyquerybooleanNoShow only servers with unlimited traffic
categoryquerystringNoFilter by server category. Allowed: compute, memory, storage, general, gpu
featured_onlyquerybooleanNoShow only featured servers

Responses

Section titled “Responses”

Returns the list of available servers matching the filters.

{
  "statusCode": 200,
  "message": "Available servers retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439014",
      "name": "node-example-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": {},
        "setup_fee": "25.00",
        "setup_fee_cents": 2500,
        "price_tiers": {}
      },
      "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
        }
      }
    }
  ]
}

GET /api/v1/offers

Section titled “GET /api/v1/offers”

Browse machines available to order with a delivery lead time. Offers report delivery_hours between 1 and 720; in-stock servers belong on /api/v1/servers/available instead.

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

This endpoint takes no parameters.

Responses

Section titled “Responses”

Returns the list of orderable offers.

{
  "statusCode": 200,
  "message": "Offers retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439050",
      "name": "node-example-1",
      "country": "DE",
      "region": "eu-central",
      "city": "Frankfurt",
      "datacenter": "FRA-DC2",
      "cpu_model": "AMD EPYC 7402P",
      "cpu_cores": 24,
      "cpu_threads": 48,
      "ram_gb": 128,
      "disks": [
        {
          "count": 2,
          "capacity_gb": 960,
          "type": "NVMe",
          "interface": "PCIe 4.0",
          "model": "Samsung PM983"
        }
      ],
      "bandwidth_mbps": 1000,
      "traffic_tb": 50,
      "traffic_unlimited": false,
      "ipv4_count": 1,
      "pricing_rules": {
        "7": 7000,
        "30": 25000
      },
      "hold_rules": {
        "7": 2,
        "30": 5
      },
      "setup_fee_cents": 2500,
      "setup_fee_rules": {
        "7": 2500,
        "30": 2500
      },
      "delivery_hours": 48,
      "setup_time_minutes": 30,
      "stock": null
    }
  ]
}

Reservations

Section titled “Reservations”

Reservations let you commit to an offer before it is fulfilled. Charges happen at reservation time.

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

Section titled “POST /api/v1/offers/{id}/reserve”

Reserve an offer. Charges immediately for the rental and any one-time setup fee.

Terminal window
curl -X POST 'https://api.hoody.com/api/v1/offers/507f1f77bcf86cd799439050/reserve' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "days": 7,
    "max_charge_cents": 9500,
    "idempotency_key": "order-2025-01-21-7f3a"
  }'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe offer identifier

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
daysnumberYesMust be one of the offer’s pricing_rules keys.
max_charge_centsnumberNoCeiling on the total debit (rent plus any one-time setup fee), in integer cents. Required for every paid reservation. Compute it as pricing_rules[days] plus setup_fee_rules[days] when that key is present, otherwise setup_fee_cents. A present override wins even when it is 0.
idempotency_keystringYesCaller-generated. Replaying it returns the original reservation, unpaid twice.
pool_idstringNoMust be a pool you own. Defaults to your default pool.

Responses

Section titled “Responses”

The reservation was created.

{
  "statusCode": 201,
  "message": "Reservation created successfully",
  "data": {
    "reservation": {
      "id": "507f1f77bcf86cd799439060",
      "offer_id": "507f1f77bcf86cd799439050",
      "days": 7,
      "state": "pending",
      "ready_by": "2025-01-23T22: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": 7000,
      "setup_fee_cents": 2500,
      "total_paid_cents": 9500,
      "offer_snapshot": {}
    },
    "replayed": false
  }
}

GET /api/v1/reservations

Section titled “GET /api/v1/reservations”

List every reservation you have placed.

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
limitqueryintegerNoMaximum number of reservations to return. Default: 50.
offsetqueryintegerNoNumber of reservations to skip. Default: 0.

Responses

Section titled “Responses”

Returns the caller’s reservations.

{
  "statusCode": 200,
  "message": "Reservations retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439060",
      "offer_id": "507f1f77bcf86cd799439050",
      "days": 7,
      "state": "pending",
      "ready_by": "2025-01-23T22: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": 7000,
      "setup_fee_cents": 2500,
      "total_paid_cents": 9500,
      "offer_snapshot": {}
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

GET /api/v1/reservations/{id}

Section titled “GET /api/v1/reservations/{id}”

Fetch a single reservation by ID.

Terminal window
curl -X GET 'https://api.hoody.com/api/v1/reservations/507f1f77bcf86cd799439060' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe reservation identifier

Responses

Section titled “Responses”

Returns the reservation.

{
  "statusCode": 200,
  "message": "Reservation retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439060",
    "offer_id": "507f1f77bcf86cd799439050",
    "days": 7,
    "state": "pending",
    "ready_by": "2025-01-23T22: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": 7000,
    "setup_fee_cents": 2500,
    "total_paid_cents": 9500,
    "offer_snapshot": {}
  }
}

Rentals

Section titled “Rentals”

Active and historical rentals. The /api/v1/servers alias routes return the same payloads as the /api/v1/rentals routes.

GET /api/v1/servers

Section titled “GET /api/v1/servers”

List all servers you currently rent. Alias for GET /api/v1/rentals.

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

This endpoint takes no parameters.

Responses

Section titled “Responses”

Returns the caller’s rentals.

{
  "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": {
        "id": "507f1f77bcf86cd799439014",
        "kvm_supported": true,
        "kvm_nested": false,
        "kvm_checked_at": "2026-10-07T12:00:00.000Z"
      }
    }
  ]
}

GET /api/v1/rentals

Section titled “GET /api/v1/rentals”

List every rental you currently hold.

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

This endpoint takes no parameters.

Responses

Section titled “Responses”

Returns the caller’s rentals.

{
  "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": {
        "id": "507f1f77bcf86cd799439014",
        "kvm_supported": true,
        "kvm_nested": false,
        "kvm_checked_at": "2026-10-07T12:00:00.000Z"
      }
    }
  ]
}

GET /api/v1/servers/{id}

Section titled “GET /api/v1/servers/{id}”

Get one rented server by ID. Alias for GET /api/v1/rentals/{id}.

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe rental identifier

Responses

Section titled “Responses”

Returns the rental.

{
  "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-example-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
        }
      },
      "kvm_supported": true,
      "kvm_nested": false,
      "kvm_checked_at": "2026-10-07T12:00:00.000Z"
    },
    "transaction": {
      "id": "507f1f77bcf86cd799439321",
      "amount": 70,
      "currency": "USD",
      "created_at": "2025-01-21T22:00:00.000Z"
    }
  }
}

GET /api/v1/rentals/{id}

Section titled “GET /api/v1/rentals/{id}”

Get one rental by ID.

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe rental identifier

Responses

Section titled “Responses”

Returns the rental.

{
  "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-example-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
        }
      },
      "kvm_supported": true,
      "kvm_nested": false,
      "kvm_checked_at": "2026-10-07T12:00:00.000Z"
    },
    "transaction": {
      "id": "507f1f77bcf86cd799439321",
      "amount": 70,
      "currency": "USD",
      "created_at": "2025-01-21T22:00:00.000Z"
    }
  }
}

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

Section titled “POST /api/v1/servers/{id}/rent”

Rent an available server. 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.

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe server identifier

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
pool_idstringNoPool to assign the rental to. Must match ^[0-9a-f]{24}$.
rental_daysintegerYesNumber of days to rent. Must match a server-priced duration, between 1 and 3650.
max_charge_centsintegerNoCeiling on the total debit (rental price plus any one-time setup fee), in integer cents. Required for every paid rental. Read it from pricing.price_tiers[rental_days].total_first_payment.

Responses

Section titled “Responses”

The rental was created.

{
  "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": 12500,
      "renewal_pricing_frozen": { "30": 8000 }
    },
    "transaction": {
      "id": "507f1f77bcf86cd799439321",
      "amount": 70,
      "currency": "USD"
    }
  }
}

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

Section titled “POST /api/v1/rentals/{id}/extend”

Extend an existing rental for additional days. Sends expected_rental_end to make replay safe.

Terminal window
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
  }'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe rental identifier

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
expected_rental_endstringYesThe rental’s current rental_end, exactly as the API returned it. The extension is applied only if it still matches.
additional_daysintegerYesNumber of additional days to extend the rental. Between 1 and 3650, must match server pricing durations.
max_charge_centsintegerNoThe total you confirmed, in whole cents. Required when the rental has no frozen renewal price.

Responses

Section titled “Responses”

The rental was extended.

{
  "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": 9500,
      "renewal_pricing_frozen": { "30": 8000 },
      "remaining_days": 13
    },
    "transaction": {
      "id": "507f1f77bcf86cd799439322",
      "amount": 70,
      "currency": "USD"
    }
  }
}

Live runtime

Section titled “Live runtime”

Short-TTL live CPU, memory, disk, and load metrics for a rented server or subserver. Polled frequently; first-party JWT only.

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

Section titled “GET /api/v1/servers/{id}/runtime”

Live runtime info for a rented server or subserver. Alias for GET /api/v1/rentals/{id}/runtime.

Terminal window
curl -X GET 'https://api.hoody.com/api/v1/servers/507f1f77bcf86cd799439014/runtime' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe rental or server identifier

Responses

Section titled “Responses”

Returns live runtime counters.

{
  "statusCode": 200,
  "message": "Runtime info retrieved successfully",
  "data": {
    "scope": "server",
    "ts": "2025-01-22T10:00:00.000Z",
    "cache_age_ms": 1500,
    "stale": false,
    "uptime_s": 86400,
    "cores": 64,
    "load": { "1": 0.42, "5": 0.38, "15": 0.31 },
    "cpu": { "busy_pct": 12.4 },
    "mem": { "used_bytes": 85899345920, "total_bytes": 274877906944, "pct": 31.2 },
    "swap": { "used_bytes": 0, "total_bytes": 8589934592 },
    "storage": { "used_bytes": 4500000000000, "total_bytes": 92000000000000, "pct": 4.9 }
  }
}

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

Section titled “GET /api/v1/rentals/{id}/runtime”

Live runtime info for a rented server or subserver.

Terminal window
curl -X GET 'https://api.hoody.com/api/v1/rentals/507f1f77bcf86cd799439014/runtime' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe rental identifier

Responses

Section titled “Responses”

Returns live runtime counters.

{
  "statusCode": 200,
  "message": "Runtime info retrieved successfully",
  "data": {
    "scope": "server",
    "ts": "2025-01-22T10:00:00.000Z",
    "cache_age_ms": 1500,
    "stale": false,
    "uptime_s": 86400,
    "cores": 64,
    "load": { "1": 0.42, "5": 0.38, "15": 0.31 },
    "cpu": { "busy_pct": 12.4 },
    "mem": { "used_bytes": 85899345920, "total_bytes": 274877906944, "pct": 31.2 },
    "swap": { "used_bytes": 0, "total_bytes": 8589934592 },
    "storage": { "used_bytes": 4500000000000, "total_bytes": 92000000000000, "pct": 4.9 }
  }
}

Pools

Section titled “Pools”

Pools group rented servers so multiple users can share them with a role.

GET /api/v1/pools

Section titled “GET /api/v1/pools”

List every pool you own or are a member of.

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

This endpoint takes no parameters.

Responses

Section titled “Responses”

Returns pools owned by or shared with the caller.

{
  "statusCode": 200,
  "message": "Pools retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439300",
      "name": "Development Team",
      "description": "Pool for development team resources",
      "is_default": false,
      "settings": {},
      "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
    }
  ]
}

POST /api/v1/pools

Section titled “POST /api/v1/pools”

Create a new pool.

Terminal window
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 }
  }'

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
namestringYesPool name. Up to 100 characters.
descriptionstringNoPool description. Up to 500 characters.
settingsobjectNoFree-form settings map.

Responses

Section titled “Responses”

The pool was created.

{
  "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": {},
    "created_at": "2025-01-21T22:00:00.000Z"
  }
}

GET /api/v1/pools/{id}

Section titled “GET /api/v1/pools/{id}”

Get detailed information about a single pool.

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe pool identifier

Responses

Section titled “Responses”

Returns the pool with its members and servers.

{
  "statusCode": 200,
  "message": "Pool retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439300",
    "name": "Development Team",
    "description": "Pool for development team resources",
    "is_default": false,
    "settings": {},
    "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-example-1",
        "rental_status": "active",
        "is_ready": true
      }
    ]
  }
}

PUT /api/v1/pools/{id}

Section titled “PUT /api/v1/pools/{id}”

Update pool details. Owner only. PATCH is also accepted on this endpoint with identical behaviour.

Terminal window
curl -X PUT 'https://api.hoody.com/api/v1/pools/507f1f77bcf86cd799439300' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Pool for staging and development workloads",
    "settings": {
      "auto_approve": false,
      "max_servers": 12
    }
  }'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe pool identifier

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
descriptionstringNoUpdated description, up to 500 characters.
settingsobjectNoReplacement settings map.

Responses

Section titled “Responses”

The pool was updated.

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

DELETE /api/v1/pools/{id}

Section titled “DELETE /api/v1/pools/{id}”

Delete a pool. Owner only. The default pool cannot be deleted.

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe pool identifier

Responses

Section titled “Responses”

The pool was deleted.

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

Pool members

Section titled “Pool members”

Invite, role-change, and remove members within a pool. Member-management endpoints require the caller to be at least an admin of the pool.

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

Section titled “POST /api/v1/pools/{id}/members”

Invite a user to join the pool. Admin or owner only.

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe pool identifier

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
usernamestringYesUsername of the user to invite. Must match ^[a-zA-Z0-9_-]+$, 1 to 100 characters.
rolestringYesRole to grant on acceptance. One of admin, user.

Responses

Section titled “Responses”

The invitation was sent.

{
  "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}

Section titled “PUT /api/v1/pools/{id}/members/{userId}”

Change a member’s role within the pool. Owner only. PATCH is also accepted on this endpoint with identical behaviour.

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe pool identifier
userIdpathstringYesThe member’s user identifier

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
rolestringYesNew role. One of admin, user.

Responses

Section titled “Responses”

The member’s role was updated.

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

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

Section titled “DELETE /api/v1/pools/{id}/members/{userId}”

Remove a member from the pool. Admin or owner only.

Terminal window
curl -X DELETE 'https://api.hoody.com/api/v1/pools/507f1f77bcf86cd799439300/members/507f1f77bcf86cd799439012' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe pool identifier
userIdpathstringYesThe member’s user identifier

Responses

Section titled “Responses”

The member was removed.

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

Pool invitations

Section titled “Pool invitations”

Manage your pending pool invitations, that is, invitations another user sent you that you have not yet accepted or rejected.

GET /api/v1/pools/invitations/pending

Section titled “GET /api/v1/pools/invitations/pending”

List every pool invitation currently pending for the authenticated caller.

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

This endpoint takes no parameters.

Responses

Section titled “Responses”

Returns pending invitations.

{
  "statusCode": 200,
  "message": "Pending invitations retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439320",
      "pool_id": "507f1f77bcf86cd799439300",
      "pool_name": "Development Team",
      "pool_description": "Pool for development team resources",
      "role": "admin",
      "invited_by": {
        "id": "507f1f77bcf86cd799439011",
        "username": "owner_jane",
        "alias": "Jane Smith"
      },
      "invited_at": "2025-01-21T22:00:00.000Z"
    }
  ]
}

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

Section titled “POST /api/v1/pools/{id}/accept”

Accept a pending pool invitation.

Terminal window
curl -X POST 'https://api.hoody.com/api/v1/pools/507f1f77bcf86cd799439320/accept' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe invitation identifier

Responses

Section titled “Responses”

The invitation was accepted.

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

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

Section titled “POST /api/v1/pools/{id}/reject”

Reject a pending pool invitation.

Terminal window
curl -X POST 'https://api.hoody.com/api/v1/pools/507f1f77bcf86cd799439320/reject' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe invitation identifier

Responses

Section titled “Responses”

The invitation was rejected.

{
  "statusCode": 200,
  "message": "Invitation rejected successfully",
  "data": {
    "success": true
  }
}
Section titled “Paid subserver plans”

The monthly plans you can buy as a paid subserver. The list mixes public plans with offers only signed-in users see, and each field’s text falls back to English when no translation exists. An auth token needs the financial.server_rental.view_marketplace permission.

GET /api/v1/subserver-plans

Section titled “GET /api/v1/subserver-plans”

List every paid subserver plan you can buy.

Terminal window
curl -X GET 'https://api.hoody.com/api/v1/subserver-plans?locale=en' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
localequerystringNoLanguage tag such as en, fr or pt-BR. Overrides Accept-Language. Unknown or invalid values are served as en.

Responses

Section titled “Responses”

Returns the plans available to the caller.

{
  "statusCode": 200,
  "message": "OK",
  "data": {
    "requested_locale": "en",
    "plans": [
      {
        "id": "507f1f77bcf86cd799439400",
        "family_id": "plan_std_8_32_500",
        "type": "standard",
        "sort_order": 10,
        "price_cents_per_month": 5000,
        "hold_days": 7,
        "resources": {
          "cpu_cores": 8,
          "ram_gb": 32,
          "disk_limit_gb": 500,
          "disk_io_read_mib": 1024,
          "disk_io_write_mib": 512,
          "network_limit_mbps": 1000,
          "max_containers": 50,
          "snapshots_per_container": 10,
          "ai_multiplier": 1
        },
        "text": {
          "title": "Standard 8",
          "description": "8 vCPU, 32 GB RAM, 500 GB NVMe.",
          "type_label": "Standard",
          "features": ["Dedicated resources", "Full root access", "Snapshots included"]
        },
        "text_locales": {
          "title": "en",
          "description": "en",
          "type_label": "en",
          "features": "en"
        }
      }
    ]
  }
}
Section titled “Paid subserver subscriptions”

The paid subserver subscriptions you own. Quote, purchase, pay held subscriptions to resume them, upgrade to a larger plan, cancel, and toggle auto-renew. Purchase, pay, and upgrade return 202 with an operation to poll for progress.

GET /api/v1/subserver-operations/{id}

Section titled “GET /api/v1/subserver-operations/{id}”

Status of one paid subserver operation (purchase, upgrade, resume, hold, wipe).

Terminal window
curl -X GET 'https://api.hoody.com/api/v1/subserver-operations/507f1f77bcf86cd799439100' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe operation identifier

Responses

Section titled “Responses”

Returns the operation’s current state.

{
  "statusCode": 200,
  "message": "OK",
  "data": {
    "id": "507f1f77bcf86cd799439100",
    "subscription_id": "507f1f77bcf86cd799439200",
    "kind": "purchase",
    "target_plan_id": "507f1f77bcf86cd799439400",
    "step": "delivering",
    "result": null,
    "charge_cents": 5000,
    "created_at": "2025-01-21T22:00:00.000Z",
    "completed_at": null
  }
}

GET /api/v1/subserver-subscriptions

Section titled “GET /api/v1/subserver-subscriptions”

List every paid subserver subscription you own.

Terminal window
curl -X GET 'https://api.hoody.com/api/v1/subserver-subscriptions?limit=50&offset=0&locale=en' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
limitqueryintegerNoMaximum number of subscriptions to return. Default: 50.
offsetqueryintegerNoNumber of subscriptions to skip. Default: 0.
localequerystringNoLanguage tag for plan.title and plan.type_label, such as en, fr or pt-BR. Overrides Accept-Language. Unknown or invalid values are served as en.

Responses

Section titled “Responses”

Returns the caller’s subscriptions with pagination totals.

{
  "statusCode": 200,
  "message": "OK",
  "data": [
    {
      "id": "507f1f77bcf86cd799439200",
      "plan_id": "507f1f77bcf86cd799439400",
      "state": "active",
      "server_id": "507f1f77bcf86cd799439210",
      "server_name": "node-example-1",
      "anchor_day": 21,
      "auto_renew": true,
      "paid_through": "2025-02-21T22:00:00.000Z",
      "active_operation_id": null,
      "delete_at": null,
      "plan": {
        "family_id": "plan_std_8_32_500",
        "title": "Standard 8",
        "type_label": "Standard",
        "price_cents_per_month": 5000,
        "hold_days": 7,
        "resources": {
          "cpu_cores": 8,
          "ram_gb": 32,
          "disk_limit_gb": 500,
          "disk_io_read_mib": 1024,
          "disk_io_write_mib": 512,
          "network_limit_mbps": 1000,
          "max_containers": 50,
          "snapshots_per_container": 10,
          "ai_multiplier": 1
        }
      },
      "created_at": "2025-01-21T22:00:00.000Z",
      "updated_at": "2025-01-21T22:30:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

GET /api/v1/subserver-subscriptions/{id}

Section titled “GET /api/v1/subserver-subscriptions/{id}”

Get one paid subserver subscription you own.

Terminal window
curl -X GET 'https://api.hoody.com/api/v1/subserver-subscriptions/507f1f77bcf86cd799439200?locale=en' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe subscription identifier
localequerystringNoLanguage tag for plan.title and plan.type_label, such as en, fr or pt-BR. Overrides Accept-Language. Unknown or invalid values are served as en.

Responses

Section titled “Responses”

Returns the subscription.

{
  "statusCode": 200,
  "message": "OK",
  "data": {
    "id": "507f1f77bcf86cd799439200",
    "plan_id": "507f1f77bcf86cd799439400",
    "state": "active",
    "server_id": "507f1f77bcf86cd799439210",
    "server_name": "node-example-1",
    "anchor_day": 21,
    "auto_renew": true,
    "paid_through": "2025-02-21T22:00:00.000Z",
    "active_operation_id": null,
    "delete_at": null,
    "plan": {
      "family_id": "plan_std_8_32_500",
      "title": "Standard 8",
      "type_label": "Standard",
      "price_cents_per_month": 5000,
      "hold_days": 7,
      "resources": {
        "cpu_cores": 8,
        "ram_gb": 32,
        "disk_limit_gb": 500,
        "disk_io_read_mib": 1024,
        "disk_io_write_mib": 512,
        "network_limit_mbps": 1000,
        "max_containers": 50,
        "snapshots_per_container": 10,
        "ai_multiplier": 1
      }
    },
    "created_at": "2025-01-21T22:00:00.000Z",
    "updated_at": "2025-01-21T22:30:00.000Z"
  }
}

GET /api/v1/subserver-subscriptions/quote

Section titled “GET /api/v1/subserver-subscriptions/quote”

Quote the cost of buying a specific plan.

Terminal window
curl -X GET 'https://api.hoody.com/api/v1/subserver-subscriptions/quote?plan_id=507f1f77bcf86cd799439400' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
plan_idquerystringYesThe plan version id from GET /api/v1/subserver-plans.

Responses

Section titled “Responses”

Returns the price, the account’s paid subserver cap, and whether a host has room.

{
  "statusCode": 200,
  "message": "OK",
  "data": {
    "action": "purchase",
    "plan_id": "507f1f77bcf86cd799439400",
    "subscription_id": null,
    "kind": null,
    "charge_cents": 5000,
    "price_cents_per_month": 5000,
    "recovery": false,
    "paid_through": null,
    "cap": { "max": 5, "used": 0 },
    "available": true
  }
}

GET /api/v1/subserver-subscriptions/{id}/quote

Section titled “GET /api/v1/subserver-subscriptions/{id}/quote”

Quote an upgrade or a payment for an existing subscription. action=upgrade with plan_id prices the upgrade for the rest of the period; action=pay prices a late payment.

Terminal window
curl -X GET 'https://api.hoody.com/api/v1/subserver-subscriptions/507f1f77bcf86cd799439200/quote?action=upgrade&plan_id=507f1f77bcf86cd799439400' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe subscription identifier
actionquerystringYesWhat to quote. One of upgrade, pay.
plan_idquerystringNoRequired for action=upgrade. The target plan version id.

Responses

Section titled “Responses”

Returns the price of the requested change.

{
  "statusCode": 200,
  "message": "OK",
  "data": {
    "action": "upgrade",
    "plan_id": "507f1f77bcf86cd799439400",
    "subscription_id": "507f1f77bcf86cd799439200",
    "kind": null,
    "charge_cents": 2500,
    "price_cents_per_month": 5000,
    "recovery": false,
    "paid_through": "2025-02-21T22:00:00.000Z",
    "cap": { "max": 5, "used": 1 },
    "available": false
  }
}

POST /api/v1/subserver-subscriptions

Section titled “POST /api/v1/subserver-subscriptions”

Buy a paid subserver. Charges the first month from your wallet and starts delivering the subserver. Quote first and pass max_charge_cents; a retried request with the same idempotency_key returns the original operation without charging again.

Terminal window
curl -X POST 'https://api.hoody.com/api/v1/subserver-subscriptions' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "plan_id": "507f1f77bcf86cd799439400",
    "idempotency_key": "sub-2025-01-21-7f3a",
    "max_charge_cents": 5000
  }'

This endpoint takes no parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
plan_idstringYesPlan version id from GET /subserver-plans.
idempotency_keystringYesCaller-generated. Replaying it returns the original operation, charged once. A refused request’s key stays refused (the same error every time): use a new key to try again.
max_charge_centsintegerNoCeiling on the debit, from the quote. Required whenever the charge is above 0.

Responses

Section titled “Responses”

The purchase was accepted and is in progress. Poll the returned operation to see when delivery finishes.

{
  "statusCode": 202,
  "message": "OK",
  "data": {
    "operation": {
      "id": "507f1f77bcf86cd799439100",
      "subscription_id": "507f1f77bcf86cd799439200",
      "kind": "purchase",
      "target_plan_id": "507f1f77bcf86cd799439400",
      "step": "queued",
      "result": null,
      "charge_cents": 5000,
      "created_at": "2025-01-21T22:00:00.000Z",
      "completed_at": null
    },
    "subscription": {
      "id": "507f1f77bcf86cd799439200",
      "plan_id": "507f1f77bcf86cd799439400",
      "state": "provisioning",
      "server_id": null,
      "server_name": null,
      "anchor_day": 21,
      "auto_renew": true,
      "paid_through": null,
      "active_operation_id": "507f1f77bcf86cd799439100",
      "delete_at": null,
      "plan": {
        "family_id": "plan_std_8_32_500",
        "title": "Standard 8",
        "type_label": "Standard",
        "price_cents_per_month": 5000,
        "hold_days": 7,
        "resources": {
          "cpu_cores": 8,
          "ram_gb": 32,
          "disk_limit_gb": 500,
          "disk_io_read_mib": 1024,
          "disk_io_write_mib": 512,
          "network_limit_mbps": 1000,
          "max_containers": 50,
          "snapshots_per_container": 10,
          "ai_multiplier": 1
        }
      },
      "created_at": "2025-01-21T22:00:00.000Z",
      "updated_at": "2025-01-21T22:00:00.000Z"
    },
    "replayed": false
  }
}

POST /api/v1/subserver-subscriptions/{id}/cancel

Section titled “POST /api/v1/subserver-subscriptions/{id}/cancel”

Cancel a paid subserver subscription. Turns auto-renew off. The subserver keeps running until paid_through, then goes on hold. No refund.

Terminal window
curl -X POST 'https://api.hoody.com/api/v1/subserver-subscriptions/507f1f77bcf86cd799439200/cancel' \
  -H 'Authorization: Bearer <token>'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe subscription identifier

Responses

Section titled “Responses”

Returns the subscription with auto_renew set to false.

{
  "statusCode": 200,
  "message": "OK",
  "data": {
    "id": "507f1f77bcf86cd799439200",
    "plan_id": "507f1f77bcf86cd799439400",
    "state": "active",
    "server_id": "507f1f77bcf86cd799439210",
    "server_name": "node-example-1",
    "anchor_day": 21,
    "auto_renew": false,
    "paid_through": "2025-02-21T22:00:00.000Z",
    "active_operation_id": null,
    "delete_at": null,
    "plan": {
      "family_id": "plan_std_8_32_500",
      "title": "Standard 8",
      "type_label": "Standard",
      "price_cents_per_month": 5000,
      "hold_days": 7,
      "resources": {
        "cpu_cores": 8,
        "ram_gb": 32,
        "disk_limit_gb": 500,
        "disk_io_read_mib": 1024,
        "disk_io_write_mib": 512,
        "network_limit_mbps": 1000,
        "max_containers": 50,
        "snapshots_per_container": 10,
        "ai_multiplier": 1
      }
    },
    "created_at": "2025-01-21T22:00:00.000Z",
    "updated_at": "2025-01-21T22:30:00.000Z"
  }
}

POST /api/v1/subserver-subscriptions/{id}/pay

Section titled “POST /api/v1/subserver-subscriptions/{id}/pay”

Pay a held subscription and resume it. Charges one month starting today (the renewal day moves to today) and resumes the subserver from its host. Months spent on hold are never charged. A failed paid recovery is retried at no charge. A subserver permanently deleted after its hold (wiping, or since deleted) cannot be paid for.

Terminal window
curl -X POST 'https://api.hoody.com/api/v1/subserver-subscriptions/507f1f77bcf86cd799439200/pay' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "pay-2025-01-21-7f3a",
    "max_charge_cents": 5000
  }'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe subscription identifier

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
idempotency_keystringYesCaller-generated. Replaying it returns the original operation, charged once. A refused request’s key stays refused (the same error every time): use a new key to try again.
max_charge_centsintegerNoCeiling on the debit, from the quote. Required whenever the charge is above 0.

Responses

Section titled “Responses”

The payment was accepted and the subserver is resuming. Poll the returned operation.

{
  "statusCode": 202,
  "message": "OK",
  "data": {
    "operation": {
      "id": "507f1f77bcf86cd799439101",
      "subscription_id": "507f1f77bcf86cd799439200",
      "kind": "resume",
      "target_plan_id": "507f1f77bcf86cd799439400",
      "step": "resuming",
      "result": null,
      "charge_cents": 5000,
      "created_at": "2025-01-21T22:00:00.000Z",
      "completed_at": null
    },
    "subscription": {
      "id": "507f1f77bcf86cd799439200",
      "plan_id": "507f1f77bcf86cd799439400",
      "state": "active",
      "server_id": "507f1f77bcf86cd799439210",
      "server_name": "node-example-1",
      "anchor_day": 21,
      "auto_renew": true,
      "paid_through": "2025-02-21T22:00:00.000Z",
      "active_operation_id": "507f1f77bcf86cd799439101",
      "delete_at": null,
      "plan": {
        "family_id": "plan_std_8_32_500",
        "title": "Standard 8",
        "type_label": "Standard",
        "price_cents_per_month": 5000,
        "hold_days": 7,
        "resources": {
          "cpu_cores": 8,
          "ram_gb": 32,
          "disk_limit_gb": 500,
          "disk_io_read_mib": 1024,
          "disk_io_write_mib": 512,
          "network_limit_mbps": 1000,
          "max_containers": 50,
          "snapshots_per_container": 10,
          "ai_multiplier": 1
        }
      },
      "created_at": "2025-01-21T22:00:00.000Z",
      "updated_at": "2025-01-21T22:30:00.000Z"
    },
    "replayed": false
  }
}

POST /api/v1/subserver-subscriptions/{id}/upgrade

Section titled “POST /api/v1/subserver-subscriptions/{id}/upgrade”

Upgrade a paid subserver. Moves the subscription to a plan with every resource equal or larger. Charges only the price difference for the rest of the current period. The subserver is stopped, changed and started again (a short downtime).

Terminal window
curl -X POST 'https://api.hoody.com/api/v1/subserver-subscriptions/507f1f77bcf86cd799439200/upgrade' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "plan_id": "507f1f77bcf86cd799439401",
    "idempotency_key": "upg-2025-01-21-7f3a",
    "max_charge_cents": 2500
  }'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe subscription identifier

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
plan_idstringYesThe target plan version id.
idempotency_keystringYesCaller-generated. Replaying it returns the original operation, charged once. A refused request’s key stays refused (the same error every time): use a new key to try again.
max_charge_centsintegerNoCeiling on the debit, from the quote. Required whenever the charge is above 0.

Responses

Section titled “Responses”

The upgrade was accepted and is in progress. Poll the returned operation.

{
  "statusCode": 202,
  "message": "OK",
  "data": {
    "operation": {
      "id": "507f1f77bcf86cd799439102",
      "subscription_id": "507f1f77bcf86cd799439200",
      "kind": "upgrade",
      "target_plan_id": "507f1f77bcf86cd799439401",
      "step": "queued",
      "result": null,
      "charge_cents": 2500,
      "created_at": "2025-01-21T22:00:00.000Z",
      "completed_at": null
    },
    "subscription": {
      "id": "507f1f77bcf86cd799439200",
      "plan_id": "507f1f77bcf86cd799439401",
      "state": "active",
      "server_id": "507f1f77bcf86cd799439210",
      "server_name": "node-example-1",
      "anchor_day": 21,
      "auto_renew": true,
      "paid_through": "2025-02-21T22:00:00.000Z",
      "active_operation_id": "507f1f77bcf86cd799439102",
      "delete_at": null,
      "plan": {
        "family_id": "plan_std_16_64_1000",
        "title": "Standard 16",
        "type_label": "Standard",
        "price_cents_per_month": 9000,
        "hold_days": 7,
        "resources": {
          "cpu_cores": 16,
          "ram_gb": 64,
          "disk_limit_gb": 1000,
          "disk_io_read_mib": 2048,
          "disk_io_write_mib": 1024,
          "network_limit_mbps": 2000,
          "max_containers": 100,
          "snapshots_per_container": 20,
          "ai_multiplier": 2
        }
      },
      "created_at": "2025-01-21T22:00:00.000Z",
      "updated_at": "2025-01-21T22:30:00.000Z"
    },
    "replayed": false
  }
}

PUT /api/v1/subserver-subscriptions/{id}/auto-renew

Section titled “PUT /api/v1/subserver-subscriptions/{id}/auto-renew”

Turn auto-renew on or off. PATCH is also accepted on this endpoint with identical behaviour.

The SDK reaches this same operation through two named methods, each of which sets the auto_renew body field on the caller’s behalf:

  • client.api.servers.subscriptions.enableAutoRenew(id) sets body auto_renew=true
  • client.api.servers.subscriptions.disableAutoRenew(id) sets body auto_renew=false
Terminal window
curl -X PUT 'https://api.hoody.com/api/v1/subserver-subscriptions/507f1f77bcf86cd799439200/auto-renew' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "auto_renew": false
  }'

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesThe subscription identifier

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
auto_renewbooleanYestrue renews the subscription from the wallet at the end of each paid period; false lets it stop when the current period ends. Only the account owner (signed in, not impersonated) or an auth token can turn it on.

Responses

Section titled “Responses”

Returns the subscription with the new auto_renew value.

{
  "statusCode": 200,
  "message": "OK",
  "data": {
    "id": "507f1f77bcf86cd799439200",
    "plan_id": "507f1f77bcf86cd799439400",
    "state": "active",
    "server_id": "507f1f77bcf86cd799439210",
    "server_name": "node-example-1",
    "anchor_day": 21,
    "auto_renew": false,
    "paid_through": "2025-02-21T22:00:00.000Z",
    "active_operation_id": null,
    "delete_at": null,
    "plan": {
      "family_id": "plan_std_8_32_500",
      "title": "Standard 8",
      "type_label": "Standard",
      "price_cents_per_month": 5000,
      "hold_days": 7,
      "resources": {
        "cpu_cores": 8,
        "ram_gb": 32,
        "disk_limit_gb": 500,
        "disk_io_read_mib": 1024,
        "disk_io_write_mib": 512,
        "network_limit_mbps": 1000,
        "max_containers": 50,
        "snapshots_per_container": 10,
        "ai_multiplier": 1
      }
    },
    "created_at": "2025-01-21T22:00:00.000Z",
    "updated_at": "2025-01-21T22:30:00.000Z"
  }
}