The Container Network API lets you inspect, configure, start, stop, and remove the network proxy or traffic-blocking profile attached to a single container. Use these endpoints when you need to manage outbound network routing, assign a proxy location, or tear down the network layer for an individual container.

Get container network configuration

Retrieve the current network configuration and runtime status for a container.

GET /api/v1/containers/{id}/network

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the container to retrieve network configuration for

cURL

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

SDK

const config = await client.api.containers.getNetworkConfig("507f1f77bcf86cd799439012");

200

{
  "statusCode": 200,
  "message": "Network configuration retrieved successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439012",
    "configured": true,
    "type": "socks5",
    "proxy": "socks5://proxy.example.com:1080",
    "credentials_configured": true,
    "country": "US",
    "city": "New York",
    "region": "North America",
    "comment": "Production proxy configuration",
    "dns_servers": ["1.1.1.1", "8.8.8.8"],
    "status": "running",
    "configured_at": "2025-01-15T10:00:00.000Z",
    "last_status_check": "2025-01-15T20:00:00.000Z",
    "remote_status": {
      "is_running": true,
      "last_check": "2025-01-15T20:00:00.000Z"
    }
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid container ID format"
}

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Access denied to this container"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to retrieve network configuration"
}

Update container network configuration

Create or replace the network proxy or blocking configuration for a container.

PUT /api/v1/containers/{id}/network

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the container to configure network for

Request body

Field	Type	Required	Description
type	string	Yes	Network configuration type. One of socks5, http, https, or block.
proxy	string	No	Proxy server URL (required for non-block types), e.g. socks5://proxy.example.com:1080. Credentials may be embedded as userinfo (socks5://host:port) to set or replace them; omitting userinfo on an unchanged endpoint preserves the stored credentials (write-only secret). The response never echoes userinfo back — see credentials_configured.
country	string	No	Optional country for geographical proxy selection.
city	string	No	Optional city for geographical proxy selection.
region	string	No	Optional region for geographical proxy selection.
comment	string	No	Optional comment describing the network configuration.
dns_servers	array	No	Custom DNS servers. Maximum of 4 entries. Defaults to ["1.1.1.1", "8.8.8.8"].

cURL

curl -X PUT "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/network" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "socks5",
    "proxy": "socks5://user:pass@proxy.example.com:1080",
    "country": "US",
    "city": "New York",
    "region": "North America",
    "comment": "Production proxy for US traffic",
    "dns_servers": ["1.1.1.1", "8.8.8.8"]
  }'

SDK

await client.api.containers.updateNetworkConfig("507f1f77bcf86cd799439012", {
  type: "socks5",
  proxy: "socks5://user:pass@proxy.example.com:1080",
  country: "US",
  city: "New York",
  region: "North America",
  comment: "Production proxy for US traffic",
  dns_servers: ["1.1.1.1", "8.8.8.8"]
});

200

{
  "statusCode": 200,
  "message": "Network configuration updated successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439012",
    "type": "socks5",
    "proxy": "socks5://proxy.example.com:1080",
    "credentials_configured": true,
    "country": "US",
    "city": "New York",
    "region": "North America",
    "comment": "Production proxy for US traffic",
    "dns_servers": ["1.1.1.1", "8.8.8.8"],
    "status": "configured",
    "configured_at": "2025-01-15T21:00:00.000Z"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Proxy URL required for non-block type"
}

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Cannot configure network for this container"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to update network configuration"
}

Start container network

Start the network proxy or blocking service for a configured container.

POST /api/v1/containers/{id}/network/start

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the container to start network for

cURL

curl -X POST "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/network/start" \
  -H "Authorization: Bearer <token>"

SDK

await client.api.containers.startNetwork("507f1f77bcf86cd799439012");

200

{
  "statusCode": 200,
  "message": "Network service started successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439012",
    "status": "running",
    "is_running": true,
    "last_check": "2025-01-15T21:05:00.000Z"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Network not configured for this container"
}

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Cannot start network for this container"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to start network service"
}

Stop container network

Stop the network proxy or blocking service for a container.

POST /api/v1/containers/{id}/network/stop

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the container to stop network for

cURL

curl -X POST "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/network/stop" \
  -H "Authorization: Bearer <token>"

SDK

await client.api.containers.stopNetwork("507f1f77bcf86cd799439012");

200

{
  "statusCode": 200,
  "message": "Network service stopped successfully",
  "data": {
    "container_id": "507f1f77bcf86cd799439012",
    "status": "stopped",
    "is_running": false,
    "last_check": "2025-01-15T21:10:00.000Z"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Network not configured for this container"
}

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Cannot stop network for this container"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to stop network service"
}

Remove container network configuration

Permanently remove the network proxy or blocking configuration from a container.

Caution

Removing a network configuration deletes the proxy credentials and routing rules. The container reverts to its default network policy and the action cannot be undone through this endpoint.

DELETE /api/v1/containers/{id}/network

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique identifier of the container to remove network configuration from

cURL

curl -X DELETE "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439012/network" \
  -H "Authorization: Bearer <token>"

SDK

await client.api.containers.removeNetworkConfig("507f1f77bcf86cd799439012");

200

{
  "statusCode": 200,
  "message": "Network configuration removed successfully"
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid container ID format"
}

401

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication required"
}

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Cannot remove network configuration from this container"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container or network configuration not found"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to remove network configuration"
}