# Server Management API

**Page:** api/server-management

[Download Raw Markdown](./api/server-management.md)

---

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



The Server Management API provides endpoints for executing predefined commands on rental servers, listing the commands available to a given server, and reading platform-level utility data such as caller IP geolocation and Hoody social channel counters. Use these endpoints to introspect which actions a server permits, run a chosen command (synchronously or asynchronously), and surface live community stats without rate-limit risk.

## Utilities

### `GET /api/v1/ip`

Retrieves information about the caller's IP address, including geolocation, network details, the `User-Agent`, the request protocol, and whether the request was logged by the platform.

This endpoint takes no parameters.

#### Example Request




```bash
curl -X GET https://api.hoody.com/api/v1/ip
```




```typescript
const response = await client.api.utilities.getIpInfo();
```




#### Example Response




```json
{
  "statusCode": 200,
  "message": "IP information retrieved successfully",
  "data": {
    "ip": "8.8.8.8",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
    "headers": {
      "accept-language": "en-US,en;q=0.9"
    },
    "referer": "https://example.com",
    "timestamp": "2025-01-15T16:00:00.000Z",
    "is_logged": true,
    "protocol": "https",
    "ip_info": {
      "ip": "8.8.8.8",
      "hostname": "dns.google",
      "city": "Mountain View",
      "region": "California",
      "country": "US",
      "loc": "37.4056,-122.0775",
      "postal": "94043",
      "timezone": "America/Los_Angeles",
      "asn": {
        "asn": "AS15169",
        "name": "Google LLC",
        "domain": "google.com"
      },
      "is_anycast": true,
      "is_mobile": false,
      "is_anonymous": false,
      "is_satellite": false,
      "is_hosting": true
    }
  }
}
```




## Meta

### `GET /api/v1/meta/social-stats`

Returns cached counters for the Hoody public social channels: GitHub stars, Telegram members, Discord members (total + currently online), X followers, and LinkedIn followers. Values are persisted to disk (`auto.json`) and refreshed in the background every 10 minutes, so this endpoint is cheap to call, has no upstream rate-limit risk, and survives process restarts even when upstreams are unreachable. A field is `null` only when no value has ever been persisted for it (for example, before the first successful refresh).

This endpoint takes no parameters and requires no authentication.

#### Example Request




```bash
curl -X GET https://api.hoody.com/api/v1/meta/social-stats
```




```typescript
const response = await client.api.meta.getSocialStats();
```




#### Example Response




```json
{
  "statusCode": 200,
  "message": "Hoody social counters",
  "data": {
    "github": 1234,
    "telegram": 5678,
    "discord": 910,
    "discord_online": 42,
    "x": 837,
    "linkedin": 560,
    "fetchedAt": "2025-01-15T16:00:00.000Z"
  }
}
```




## Server Commands

### `GET /api/v1/servers/{serverId}/available-commands`

Lists the commands available for execution on a given server. Results can be filtered by `category` and by a maximum acceptable `risk_level`. The response includes a `server_info` block describing the target server.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `serverId` | path | string | Yes | Server ID to get available commands for |
| `category` | query | string | No | Filter by command category |
| `risk_level` | query | string | No | Filter by maximum risk level. Allowed values: `low`, `medium`, `high`, `critical` |

#### Example Request




```bash
curl -X GET "https://api.hoody.com/api/v1/servers/507f1f77bcf86cd799439012/available-commands?category=system&risk_level=medium"
```




```typescript
const iterator = client.api.serverCommands.listIterator({
  serverId: "507f1f77bcf86cd799439012",
  category: "system",
  risk_level: "medium"
});

for await (const page of iterator) {
  // process page.data.commands
}
```




#### Example Response




```json
{
  "statusCode": 200,
  "message": "Available commands retrieved successfully",
  "data": {
    "commands": [
      {
        "id": "507f1f77bcf86cd799439015",
        "name": "Restart Service",
        "slug": "restart-service",
        "description": "Restart a system service",
        "category": "system",
        "mode": "ssh",
        "risk_level": "medium",
        "requires_confirmation": true,
        "parameter_schema": {
          "type": "object",
          "required": ["service_name"]
        },
        "example_parameters": {
          "service_name": "nginx"
        },
        "default_timeout": 300,
        "cooldown_seconds": 600,
        "rate_limit_per_hour": 10,
        "rate_limit_per_day": 50
      }
    ],
    "server_info": {
      "id": "507f1f77bcf86cd799439012",
      "name": "node-us-east-1",
      "is_ready": true,
      "rental_status": "active"
    }
  }
}
```




### `POST /api/v1/servers/{serverId}/execute-command`

Executes a predefined command on the given server. Identify the command by `command_id` (24-character hex) or `command_slug` (lowercase, hyphenated). The request is `oneOf` — exactly one of `command_id` or `command_slug` is required. High-risk commands require a `confirmation_token`. When `wait` is `true` (the default), the request blocks until the command finishes; otherwise the API returns `202 Accepted` and the command runs in the background.


The `timeout` value cannot exceed the command's configured `max_timeout`. Requests above this cap will be rejected with `400`.


#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `serverId` | path | string | Yes | Server ID to execute command on |

#### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `command_id` | string | No | Command ID to execute. Must be a 24-character hex string. Provide either `command_id` or `command_slug`. |
| `command_slug` | string | No | Command slug to execute. Must match `^[a-z0-9-]+$`. Provide either `command_id` or `command_slug`. |
| `parameters` | object | No | Parameters used to render the command template before execution. |
| `wait` | boolean | No | When `true` (default), the request blocks until the command completes. When `false`, the API responds `202 Accepted` and runs the command asynchronously. |
| `timeout` | number | No | Command timeout in seconds. Minimum `1`, maximum `7200`. Cannot exceed the command's configured `max_timeout`. |
| `confirmation_token` | string | No | Required for high-risk commands. Obtained from the confirmation step. |

#### Example Request




```bash
curl -X POST https://api.hoody.com/api/v1/servers/507f1f77bcf86cd799439012/execute-command \
  -H "Content-Type: application/json" \
  -d '{
    "command_slug": "restart-service",
    "parameters": { "service_name": "nginx" },
    "wait": true,
    "timeout": 300
  }'
```




```typescript
const response = await client.api.serverCommands.execute({
  serverId: "507f1f77bcf86cd799439012",
  data: {
    command_slug: "restart-service",
    parameters: { service_name: "nginx" },
    wait: true,
    timeout: 300
  }
});
```




#### Example Response




Returned when `wait: true` and the command completes successfully.

```json
{
  "statusCode": 200,
  "message": "Command executed successfully",
  "data": {
    "command_log_id": "507f1f77bcf86cd799439016",
    "command_id": "507f1f77bcf86cd799439015",
    "status": "completed",
    "output": "Service restarted successfully",
    "exit_code": 0,
    "execution_time": 2453,
    "start_time": "2025-01-15T16:00:00.000Z",
    "end_time": "2025-01-15T16:00:02.453Z"
  }
}
```




Returned when `wait: false`. The command is queued for background execution.

```json
{
  "statusCode": 202,
  "message": "Command accepted for execution",
  "data": {
    "command_log_id": "507f1f77bcf86cd799439016",
    "command_id": "507f1f77bcf86cd799439015",
    "status": "pending",
    "estimated_completion": "2025-01-15T16:05:00.000Z"
  }
}
```




Returned for malformed requests, missing required parameters, or `timeout` exceeding the command's `max_timeout`.

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid command parameters",
  "data": {}
}
```




Returned when the caller is not authorized to execute the requested command on the target server (for example, missing `confirmation_token` for a high-risk command).

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Not authorized to execute this command on server"
}
```




Returned when either the server or the referenced command cannot be found.

```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Command or server not found"
}
```




Returned when the command's per-hour or per-day rate limit has been exceeded. The response indicates when to retry and which limit was hit.

```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded for this command",
  "data": {
    "retry_after": 3600,
    "rate_limit_type": "hourly"
  }
}
```