Proxy aliases let you create memorable, share-friendly domain names for your containers. Instead of sharing URLs that expose your project and container IDs, you can mask them behind a short, human-readable alias. Use these endpoints to list, create, update, enable/disable, and delete proxy aliases for any container you own.

Tip

A proxy alias renames the URL segment that precedes the server hostname. For example, https://a1b2c3d4-.node-sg-sin-1.containers.hoody.icu/ becomes https://my-app.node-sg-sin-1.containers.hoody.icu/. Aliases are globally unique across your account.

List proxy aliases

Returns all proxy aliases for the authenticated account, with optional filters for project, container, realm, enabled state, and expiration.

GET /api/v1/proxy/aliases

Parameters

Name	In	Type	Required	Description
project_id	query	string	No	Filter by project ID
container_id	query	string	No	Filter by container ID
realm_id	query	string	No	Filter by realm ID. Alternative to using realm subdomain in URL.
enabled	query	string	No	Filter by enabled status. Allowed values: true, false
expired	query	string	No	Filter by expiration. Allowed values: true (only expired), false (only non-expired)

Response

200

{
  "statusCode": 200,
  "message": "Proxy aliases retrieved successfully",
  "data": {
    "aliases": [
      {
        "id": "507f1f77bcf86cd799439022",
        "user_id": "507f1f77bcf86cd799439077",
        "project_id": "507f1f77bcf86cd799439033",
        "container_id": "507f1f77bcf86cd799439011",
        "alias": "my-portfolio",
        "program": "web",
        "index": 1,
        "target_path": null,
        "allow_path_override": true,
        "expires_at": null,
        "enabled": true,
        "created_at": "2025-01-15T10:30:00.000Z",
        "updated_at": "2025-01-15T10:30:00.000Z",
        "server_id": "507f1f77bcf86cd799439044",
        "server_name": "node-sg-sin-1",
        "url": "https://my-portfolio.node-sg-sin-1.containers.hoody.icu"
      },
      {
        "id": "507f1f77bcf86cd799439055",
        "user_id": "507f1f77bcf86cd799439077",
        "project_id": "507f1f77bcf86cd799439033",
        "container_id": "507f1f77bcf86cd799439066",
        "alias": "c3a8f1b2e4d5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3",
        "program": "api",
        "index": 1,
        "target_path": "/v1",
        "allow_path_override": true,
        "expires_at": "2025-06-30T23:59:59.000Z",
        "enabled": true,
        "created_at": "2025-01-10T08:00:00.000Z",
        "updated_at": "2025-01-10T08:00:00.000Z",
        "server_id": "507f1f77bcf86cd799439044",
        "server_name": "node-sg-sin-1",
        "subserver_name": "user-slice-7",
        "url": "https://c3a8f1b2e4d5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3.node-sg-sin-1.containers.hoody.icu"
      }
    ],
    "count": 2
  }
}

SDK

const { data } = await client.api.proxyAliases.listIterator({
  project_id: "507f1f77bcf86cd799439033",
  enabled: "true"
});

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.hoody.icu/api/v1/proxy/aliases?project_id=507f1f77bcf86cd799439033&enabled=true"

Get proxy alias by ID

Retrieves detailed information about a single proxy alias, including related project and container details.

GET /api/v1/proxy/aliases/{id}

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Proxy alias ID

Response

200

{
  "statusCode": 200,
  "message": "Proxy alias retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439022",
    "user_id": "507f1f77bcf86cd799439077",
    "project_id": "507f1f77bcf86cd799439033",
    "container_id": "507f1f77bcf86cd799439011",
    "alias": "my-app",
    "program": "web",
    "index": 1,
    "target_path": "/api",
    "allow_path_override": true,
    "expires_at": "2025-12-31T23:59:59.000Z",
    "enabled": true,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "url": "https://my-app.node-sg-sin-1.containers.hoody.icu",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-sg-sin-1",
    "subserver_name": "user-slice-7",
    "project": {
      "id": "507f1f77bcf86cd799439033",
      "alias": "production"
    },
    "container": {
      "id": "507f1f77bcf86cd799439011",
      "name": "web-app-1"
    }
  }
}

404

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

SDK

const { data } = await client.api.proxyAliases.get({
  id: "507f1f77bcf86cd799439022"
});

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.hoody.icu/api/v1/proxy/aliases/507f1f77bcf86cd799439022"

Create a new proxy alias

Creates a custom domain alias for one of your containers. You can provide a custom alias (3–61 chars) or pass null/false to let the system auto-generate a 48-character hex string for maximum obscurity.

POST /api/v1/proxy/aliases

Request Body

Field	Type	Required	Default	Description
container_id	string	Yes	—	Container ID that this alias points to. You must own this container.
program	string	Yes	—	Program name (must exist in container-programs.json). Common values: web, api, ssh, vnc, code-server.
alias	string | null | boolean	No	—	Custom alias name (a-z, 0-9, hyphens only; 3–61 chars; cannot start or end with a hyphen) OR null/false for an auto-generated 48-char hex. Must be unique across your account.
index	integer	No	—	Program instance index. Defaults to 1. Use when running multiple instances of the same program.
target_path	string | null	No	—	Base path for routing. Requests to https://{alias}.../ are forwarded to the container with this path prefix. Auto-prefixed with / if missing. Set to null for no path prefix.
allow_path_override	boolean	No	true	Whether to allow paths beyond target_path. If false, only the exact target_path is accessible.
expires_at	string | null	No	—	Optional ISO 8601 expiration date. Alias is automatically disabled after this date. Set to null for no expiration.
enabled	boolean	No	true	Whether the alias is initially enabled.

{
  "container_id": "507f1f77bcf86cd799439011",
  "alias": "my-portfolio",
  "program": "web",
  "index": 1,
  "target_path": null,
  "allow_path_override": true
}

Response

201

{
  "statusCode": 201,
  "message": "Proxy alias created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439022",
    "user_id": "507f1f77bcf86cd799439077",
    "project_id": "507f1f77bcf86cd799439033",
    "container_id": "507f1f77bcf86cd799439011",
    "alias": "my-app",
    "program": "web",
    "index": 1,
    "target_path": "/api",
    "allow_path_override": true,
    "expires_at": "2025-12-31T23:59:59.000Z",
    "enabled": true,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-sg-sin-1",
    "subserver_name": "user-slice-7",
    "url": "https://my-app.node-sg-sin-1.containers.hoody.icu"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid alias format."
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid input parameters	One or more request parameters failed validation.	Check the error message for specific field requirements and correct your input.
INVALID_ALIAS_FORMAT	Invalid Alias Format	The alias contains invalid characters or does not meet length requirements.	Alias must be 3–61 characters, contain only a-z, 0-9, and hyphens (not at start/end).

401

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

Error Code	Title	Description	Resolution
MISSING_TOKEN	Authentication token missing	No authentication token was provided in the request.	Include a valid JWT token in the Authorization header as Bearer <token>.
INVALID_TOKEN	Invalid authentication token	The provided authentication token is malformed or invalid.	Obtain a new token by logging in again or using a valid auth token.

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action.	Contact the resource owner or administrator to request access.

404

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

Error Code	Title	Description	Resolution
CONTAINER_NOT_FOUND	Container not found	The requested container does not exist or you do not have permission to access it.	Verify the container ID is correct and that you have access to the project it belongs to.

409

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Alias is already in use."
}

Error Code	Title	Description	Resolution
ALIAS_IN_USE	Alias In Use	The requested alias is already in use by another user or project.	Choose a different alias.

SDK

const { data } = await client.api.proxyAliases.create({
  data: {
    container_id: "507f1f77bcf86cd799439011",
    alias: "my-portfolio",
    program: "web",
    target_path: null,
    allow_path_override: true
  }
});

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "container_id": "507f1f77bcf86cd799439011",
    "alias": "my-portfolio",
    "program": "web",
    "target_path": null,
    "allow_path_override": true
  }' \
  "https://api.hoody.icu/api/v1/proxy/aliases"

Update proxy alias

Partially updates an existing proxy alias. Only the fields included in the request body are changed. Renaming the alias field also renames the underlying file on the server.

PATCH /api/v1/proxy/aliases/{id}

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Proxy alias ID to update

Request Body

Field	Type	Required	Description
alias	string	No	New alias name. Must be unique across your account.
program	string	No	Program name from container-programs.json.
index	integer	No	Program instance index.
target_path	string | null	No	Base path for routing. Set to null to remove the path prefix.
allow_path_override	boolean	No	Whether to allow paths beyond target_path.
expires_at	string | number | null	No	Expiration date (ISO string, Unix timestamp seconds/ms, or null to remove expiration).
enabled	boolean	No	Whether the alias is enabled.

{
  "alias": "my-new-name"
}

Response

200

{
  "statusCode": 200,
  "message": "Proxy alias updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439022",
    "user_id": "507f1f77bcf86cd799439077",
    "project_id": "507f1f77bcf86cd799439033",
    "container_id": "507f1f77bcf86cd799439011",
    "alias": "updated-app-name",
    "program": "api",
    "index": 2,
    "target_path": "/v2",
    "allow_path_override": false,
    "expires_at": null,
    "enabled": true,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z",
    "url": "https://updated-app-name.node-sg-sin-1.containers.hoody.icu",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-sg-sin-1",
    "subserver_name": "user-slice-7"
  }
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed"
}

404

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

409

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Alias is already in use."
}

SDK

const { data } = await client.api.proxyAliases.update({
  id: "507f1f77bcf86cd799439022",
  data: {
    alias: "my-new-name"
  }
});

curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "alias": "my-new-name" }' \
  "https://api.hoody.icu/api/v1/proxy/aliases/507f1f77bcf86cd799439022"

Enable or disable proxy alias

Toggles a proxy alias on or off without deleting it. Disabled aliases immediately stop resolving and return 404, but can be re-enabled later.

PATCH /api/v1/proxy/aliases/{id}/state

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Proxy alias ID

Request Body

Field	Type	Required	Description
enabled	boolean	Yes	Set to true to enable, false to disable.

{
  "enabled": false
}

Response

200

{
  "statusCode": 200,
  "message": "Proxy alias disabled successfully",
  "data": {
    "id": "507f1f77bcf86cd799439022",
    "user_id": "507f1f77bcf86cd799439077",
    "project_id": "507f1f77bcf86cd799439033",
    "container_id": "507f1f77bcf86cd799439011",
    "alias": "my-app",
    "program": "web",
    "index": 1,
    "target_path": "/api",
    "allow_path_override": true,
    "expires_at": "2025-12-31T23:59:59.000Z",
    "enabled": false,
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T14:45:00.000Z",
    "url": "https://my-app.node-sg-sin-1.containers.hoody.icu",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-sg-sin-1",
    "subserver_name": "user-slice-7"
  }
}

404

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

SDK

const { data } = await client.api.proxyAliases.setState({
  id: "507f1f77bcf86cd799439022",
  data: { enabled: false }
});

curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }' \
  "https://api.hoody.icu/api/v1/proxy/aliases/507f1f77bcf86cd799439022/state"

Delete proxy alias

Permanently deletes a proxy alias and removes its file from the server. The alias URL returns 404 immediately and cannot be recovered.

Caution

This action is irreversible. To temporarily stop an alias from resolving, use the Enable or disable proxy alias endpoint instead.

DELETE /api/v1/proxy/aliases/{id}

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Proxy alias ID to delete

Response

200

{
  "statusCode": 200,
  "message": "Proxy alias deleted successfully"
}

404

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

SDK

await client.api.proxyAliases.delete({
  id: "507f1f77bcf86cd799439022"
});

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.hoody.icu/api/v1/proxy/aliases/507f1f77bcf86cd799439022"