Skip to content
Hoody Documentation
Download Page (.md)

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

Section titled “Utilities”

GET /api/v1/ip

Section titled “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

Section titled “Example Request”
Terminal window
curl -X GET https://api.hoody.com/api/v1/ip

Example Response

Section titled “Example Response”
{
  "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

Section titled “Meta”

GET /api/v1/meta/social-stats

Section titled “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

Section titled “Example Request”
Terminal window
curl -X GET https://api.hoody.com/api/v1/meta/social-stats

Example Response

Section titled “Example Response”
{
  "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

Section titled “Server Commands”

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

Section titled “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

Section titled “Parameters”
NameInTypeRequiredDescription
serverIdpathstringYesServer ID to get available commands for
categoryquerystringNoFilter by command category
risk_levelquerystringNoFilter by maximum risk level. Allowed values: low, medium, high, critical

Example Request

Section titled “Example Request”
Terminal window
curl -X GET "https://api.hoody.com/api/v1/servers/507f1f77bcf86cd799439012/available-commands?category=system&risk_level=medium"

Example Response

Section titled “Example Response”
{
  "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

Section titled “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.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
serverIdpathstringYesServer ID to execute command on

Request Body

Section titled “Request Body”
FieldTypeRequiredDescription
command_idstringNoCommand ID to execute. Must be a 24-character hex string. Provide either command_id or command_slug.
command_slugstringNoCommand slug to execute. Must match ^[a-z0-9-]+$. Provide either command_id or command_slug.
parametersobjectNoParameters used to render the command template before execution.
waitbooleanNoWhen true (default), the request blocks until the command completes. When false, the API responds 202 Accepted and runs the command asynchronously.
timeoutnumberNoCommand timeout in seconds. Minimum 1, maximum 7200. Cannot exceed the command’s configured max_timeout.
confirmation_tokenstringNoRequired for high-risk commands. Obtained from the confirmation step.

Example Request

Section titled “Example Request”
Terminal window
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
  }'

Example Response

Section titled “Example Response”

Returned when wait: true and the command completes successfully.

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