Server Management API

The Server Management API provides utilities for inspecting the caller’s network context, reading cached platform meta counters, and executing predefined commands on servers under your account. Use these endpoints to fingerprint incoming requests, surface live social counters on dashboards, and run safe, audited server actions without opening interactive SSH sessions.

All control-plane endpoints are served from https://api.hoody.com and authenticate with a Hoody bearer token.

Utilities

GET /api/v1/ip

Retrieves information about the caller’s IP address, including geolocation and network details resolved from the upstream ipinfo-style provider.

This endpoint takes no parameters.

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.utilities.getIpInfo();

200

{
  "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",
    "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.3860,-122.0838",
      "postal": "94035",
      "timezone": "America/Los_Angeles",
      "asn": {
        "asn": "AS15169",
        "name": "Google LLC",
        "domain": "google.com",
        "route": "8.8.8.0/24",
        "type": "hosting"
      },
      "is_anycast": false,
      "is_mobile": false,
      "is_anonymous": false,
      "is_satellite": false,
      "is_hosting": true
    }
  }
}

Meta

GET /api/v1/meta/social-stats

Returns cached counters for the public Hoody social channels: GitHub stars, Telegram members, Discord members (total plus currently online), X followers, and LinkedIn followers. Values are persisted to disk and refreshed in the background (default every 10 minutes), so the endpoint is cheap, 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, first boot before the first successful refresh). Once populated it stays populated until manually cleared.

No authentication is required.

This endpoint takes no parameters.

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

await client.api.meta.getSocialStats();

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

Server Commands

Server commands are predefined, audited actions that can be executed remotely on a server you have access to. Before executing a command, list the catalog for the target server to discover the command’s id, slug, parameter schema, risk level, and rate limits.

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

Returns the list of commands available for execution on the specified server, optionally filtered by category or maximum risk level.

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

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

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

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

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

Executes a predefined command on the specified server. Pass either command_id or command_slug to identify the command. High-risk commands require a confirmation_token. Set wait to false to receive an immediate 202 Accepted response with a log id instead of waiting for completion.

Parameters

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

Request Body

Field	Type	Required	Default	Description
command_id	string	No	—	Command ID to execute. Mutually exclusive with command_slug; exactly one of the two is required. Must match ^[0-9a-f]{24}$.
command_slug	string	No	—	Command slug to execute. Mutually exclusive with command_id; exactly one of the two is required. Must match ^[a-z0-9-]+$.
parameters	object	No	—	Parameters for command template processing
wait	boolean	No	true	Wait for command completion before returning
timeout	number	No	—	Command timeout in seconds, between 1 and 7200. Cannot exceed the command’s max_timeout.
confirmation_token	string	No	—	Confirmation token for high-risk commands

cURL

curl -X POST "https://api.hoody.com/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": 300
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

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

200

Command completed synchronously and returned its full output.

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

Command was accepted for asynchronous execution. Poll the command log or subscribe to updates to retrieve the final result.

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