# Servers

**Page:** api/servers

[Download Raw Markdown](./api/servers.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



The Servers API provides endpoints for browsing the rental marketplace, renting servers, managing rentals, and coordinating team access through pools. Use these endpoints to find available servers, create and manage rentals, organize servers into shared pools, and invite team members.

## Pools

Pools let teams share access to rented servers. Pool owners can invite members, assign roles, and manage which servers belong to the pool.

### `GET /api/v1/pools`

Get all pools the user owns or is a member of.

This endpoint takes no parameters.



```json
{
  "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
    }
  ]
}
```


```ts
const pools = await client.api.pools.listIterator();
```



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

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

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Pool identifier |



```json
{
  "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-us-nyc-1",
        "rental_status": "active",
        "is_ready": true
      }
    ]
  }
}
```


```ts
const pool = await client.api.pools.get({ id: "507f1f77bcf86cd799439300" });
```



### `POST /api/v1/pools`

Create a new pool for team collaboration.

This endpoint takes no parameters.

### 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 | Arbitrary pool settings |

```json
{
  "name": "Production Team",
  "description": "Pool for production environment management",
  "settings": {
    "auto_approve": true,
    "max_servers": 20
  }
}
```



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


```ts
const pool = await client.api.pools.create({
  data: {
    name: "Production Team",
    description: "Pool for production environment management",
    settings: { auto_approve: true, max_servers: 20 }
  }
});
```



### `PATCH /api/v1/pools/{id}`

Update pool details. Only the pool owner may update a pool.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Pool identifier |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `description` | string | No | Updated description (max 500 characters) |
| `settings` | object | No | Updated pool settings |

```json
{
  "description": "Pool for staging and production environments",
  "settings": {
    "auto_approve": false,
    "max_servers": 15
  }
}
```



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


```ts
await client.api.pools.update({
  id: "507f1f77bcf86cd799439301",
  data: { description: "Pool for staging and production environments" }
});
```



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

Delete a pool. Only the owner may delete a pool, and the default pool cannot be deleted.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Pool identifier |



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


```ts
await client.api.pools.delete({ id: "507f1f77bcf86cd799439301" });
```



## Pool Invitations

Users receive invitations to join pools. The endpoints below let users review, accept, and reject pending invitations.

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

Get all pending pool invitations for the authenticated user.

This endpoint takes no parameters.



```json
{
  "statusCode": 200,
  "message": "Pending invitations retrieved successfully",
  "data": [
    {
      "id": "507f1f77bcf86cd799439312",
      "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-20T14:30:00.000Z"
    }
  ]
}
```


```ts
const invitations = await client.api.poolInvitations.list();
```



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

Accept an invitation to join a pool.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Invitation identifier |



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


```ts
await client.api.poolInvitations.accept({ id: "507f1f77bcf86cd799439312" });
```



### `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 |




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


```ts
await client.api.poolInvitations.reject({ id: "507f1f77bcf86cd799439312" });
```



## Pool Members

Pool admins and owners can invite new members, change member roles, and remove members from a pool.

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

Invite a user to join the pool. Requires admin or owner privileges.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Pool identifier |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `username` | string | Yes | Username of the user to invite (1-100 chars, alphanumeric, underscore, dash) |
| `role` | string | Yes | Role to assign. One of `admin`, `user` |

```json
{
  "username": "new_developer",
  "role": "user"
}
```



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


```ts
await client.api.poolMembers.invite({
  id: "507f1f77bcf86cd799439300",
  data: { username: "new_developer", role: "user" }
});
```



### `PATCH /api/v1/pools/{id}/members/{userId}`

Update a member's role in the pool. Only the pool owner may change roles.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Pool identifier |
| `userId` | path | string | Yes | Member user identifier |

### Request Body

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

```json
{
  "role": "admin"
}
```



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


```ts
await client.api.poolMembers.updateRole({
  id: "507f1f77bcf86cd799439300",
  userId: "507f1f77bcf86cd799439012",
  data: { role: "admin" }
});
```



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

Remove a member from the pool. Requires admin or owner privileges.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Pool identifier |
| `userId` | path | string | Yes | Member user identifier |



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


```ts
await client.api.poolMembers.remove({
  id: "507f1f77bcf86cd799439300",
  userId: "507f1f77bcf86cd799439012"
});
```



## Rentals

The rentals endpoints let users list active and historical rentals, retrieve rental details, and extend ongoing rentals.

### `GET /api/v1/rentals`

Get all rentals for the authenticated user.

This endpoint takes no parameters.



```json
{
  "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"
      }
    }
  ]
}
```


```ts
const rentals = await client.api.rentals.listIterator();
```



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

Get detailed information about a specific rental, including the associated server and transaction.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Rental identifier |



```json
{
  "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",
    "remaining_days": 6,
    "usage_days": 1,
    "server_id": "507f1f77bcf86cd799439014",
    "pool_id": "507f1f77bcf86cd799439300",
    "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"
    }
  }
}
```


```ts
const rental = await client.api.rentals.get({ id: "507f1f77bcf86cd799439320" });
```



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

Extend an existing rental for additional days. The number of days must match a supported pricing duration for the underlying server.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Rental identifier |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `additional_days` | number | Yes | Number of additional days to extend the rental (minimum 1; must match a server pricing duration) |

```json
{
  "additional_days": 7
}
```



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


```ts
await client.api.rentals.extend({
  id: "507f1f77bcf86cd799439320",
  data: { additional_days: 7 }
});
```



## Server Marketplace

Browse available servers and initiate new rentals. Servers can be rented for a specific duration and optionally assigned to a pool.

### `GET /api/v1/servers/available`

Browse the rental marketplace. Use the query parameters to filter by location, price, hardware specifications, and category.

### 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 |



```json
{
  "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,
      "pricing": {
        "prices": {},
        "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
        }
      }
    }
  ]
}
```


```ts
const marketplace = await client.api.serverRental.browseIterator({
  country: "US",
  max_price_per_day: 15,
  min_cpu_cores: 32
});
```



### `GET /api/v1/servers`

Alias for `GET /rentals`. Returns all rented servers for the authenticated user.

This endpoint takes no parameters.



```json
{
  "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",
        "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
          }
        }
      }
    }
  ]
}
```


```ts
const servers = await client.api.serverRental.listIterator();
```



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

Alias for `GET /rentals/{id}`. Returns detailed information about a specific rented server.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Server rental identifier |



```json
{
  "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",
    "remaining_days": 6,
    "usage_days": 1,
    "server_id": "507f1f77bcf86cd799439014",
    "pool_id": "507f1f77bcf86cd799439300",
    "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"
    }
  }
}
```


```ts
const server = await client.api.serverRental.get({ id: "507f1f77bcf86cd799439320" });
```



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

Rent an available server for a specified duration. The `rental_days` value must match a pricing duration supported by the server. Optionally, the rental can be assigned to one of the user's pools.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `id` | path | string | Yes | Server identifier |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `pool_id` | string | No | Optional pool to assign the rental to (24-character hex ID) |
| `rental_days` | number | Yes | Number of days to rent (minimum 1; must match a server pricing duration) |

```json
{
  "rental_days": 7,
  "pool_id": "507f1f77bcf86cd799439300"
}
```



```json
{
  "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"
    },
    "transaction": {
      "id": "507f1f77bcf86cd799439321",
      "amount": 70,
      "currency": "USD"
    }
  }
}
```


```ts
const result = await client.api.serverRental.rent({
  id: "507f1f77bcf86cd799439014",
  data: { rental_days: 7, pool_id: "507f1f77bcf86cd799439300" }
});
```