Server Management API

The Server Management API lets you execute predefined commands on managed servers, enumerate the commands a caller is allowed to run, inspect caller-side network metadata, and read cached platform counters such as social channel statistics.

Use this page when you need to:

• Enumerate the predefined commands available on a server, including risk level, parameter schema, and rate limits
• Execute a command synchronously or asynchronously and observe the output, exit code, and timing
• Inspect geolocation, ASN, and network-class metadata for the caller’s IP
• Display cached GitHub, Telegram, Discord, X, and LinkedIn counters without hitting upstream APIs

Server Commands

List available commands

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

Returns the set of predefined commands that the authenticated caller may execute on the specified server, including risk level, parameter schema, example parameters, default timeout, cooldown, and per-command rate limits. Use the category and risk_level filters to narrow the list.

This endpoint takes no body.

Parameters

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

Request

cURL

curl -X GET "https://api.hoody.icu/api/v1/servers/507f1f77bcf86cd799439012/available-commands?category=system&risk_level=medium" \
  -H "Authorization: Bearer <token>"

SDK

await client.api.serverCommands.listIterator("507f1f77bcf86cd799439012", { category: "system", risk_level: "medium" })

Response

200

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

Execute server command

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

Executes a predefined command on a server. The target command may be referenced by command_id or command_slug; one of them is required. Parameter values are substituted into the command template. High-risk commands require a confirmation_token issued by a prior confirmation step.

When wait is true (the default), the response includes the completed output and exit code. When wait is false, the API returns immediately with HTTP 202 and a command_log_id you can poll for completion.

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 (one of command_id or command_slug is required)
command_slug	string	No	Command slug to execute (one of command_id or command_slug is required)
parameters	object	No	Parameters for command template processing
wait	boolean	No	Wait for command completion before returning. Default: true.
timeout	number	No	Command timeout in seconds. Cannot exceed the command’s max_timeout.
confirmation_token	string	No	Confirmation token for high-risk commands

Request

cURL

curl -X POST "https://api.hoody.icu/api/v1/servers/507f1f77bcf86cd799439012/execute-command" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "command_slug": "restart-service",
    "parameters": {
      "service_name": "nginx"
    },
    "wait": true,
    "timeout": 120
  }'

SDK

await client.api.serverCommands.execute("507f1f77bcf86cd799439012", {
  command_slug: "restart-service",
  parameters: {
    service_name: "nginx"
  },
  wait: true,
  timeout: 120
})

Response

200

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

202

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

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid command parameters",
  "data": {
    "missing_params": ["service_name"]
  }
}

403

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

404

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

429

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

Utilities

Get IP information

GET /api/v1/ip

Returns geolocation, ASN, and network-class metadata about the caller’s IP, together with the user agent, referer, and protocol observed on the incoming request. Useful for diagnostics, rate-limit reasoning, or tailoring behaviour to the caller’s network.

This endpoint takes no parameters and no body.

Request

cURL

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

SDK

await client.api.utilities.getIpInfo()

Response

200

{
  "statusCode": 200,
  "message": "IP information retrieved successfully",
  "data": {
    "ip": "8.8.8.8",
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36",
    "headers": {
      "accept-language": "en-US,en;q=0.9"
    },
    "referer": "https://example.com",
    "timestamp": "2023-10-27T10:00:00Z",
    "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": {},
      "is_anycast": true,
      "is_mobile": false,
      "is_anonymous": false,
      "is_satellite": false,
      "is_hosting": true
    }
  }
}

Meta

Get Hoody social counters

GET /api/v1/meta/social-stats

Returns cached counters for the public Hoody social channels: GitHub stars, Telegram members, Discord members (total and currently online), X followers, and LinkedIn followers.

Tip

Values are persisted to disk and refreshed in the background (default 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 example, before the first successful refresh); once populated it stays populated until manually cleared.

No authentication is required.

This endpoint takes no parameters and no body.

Request

cURL

curl -X GET "https://api.hoody.icu/api/v1/meta/social-stats"

SDK

await client.api.meta.getSocialStats()

Response

200

{
  "statusCode": 200,
  "message": "Hoody social counters",
  "data": {
    "github": 1234,
    "telegram": 5678,
    "discord": 910,
    "discord_online": 42,
    "x": 837,
    "linkedin": 560,
    "fetchedAt": "2026-05-02T12:00:00.000Z"
  }
}