Overview

Proxy aliases let you share a container using a custom, human-readable subdomain instead of the default project-and-container-id hostname. For example, you can share https://my-app.node-sg-sin-1.containers.hoody.icu/ instead of https://507f1f77bcf86cd799439033-507f1f77bcf86cd799439011.node-sg-sin-1.containers.hoody.icu/. Use the endpoints on this page to list, create, update, enable/disable, or delete proxy aliases scoped to your account.

List proxy aliases

GET /api/v1/proxy/aliases

List all proxy aliases for your account. Supports optional filtering by project, container, realm, enabled status, and expiration.

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. "true" = only expired, "false" = only non-expired. Allowed values: "true", "false".

cURL

curl -X GET "https://api.hoody.icu/api/v1/proxy/aliases?project_id=507f1f77bcf86cd799439033&enabled=true" \
  -H "Authorization: Bearer <token>"

SDK

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

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": "http",
        "index": 3000,
        "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",
        "project_id": "507f1f77bcf86cd799439033",
        "container_id": "507f1f77bcf86cd799439066",
        "alias": "c3a8f1b2e4d5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3",
        "program": "https",
        "index": 8443,
        "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
  }
}

Get proxy alias by ID

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

Retrieve detailed information about a specific proxy alias, including the associated project and container.

Parameters

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

cURL

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

SDK

const result = await client.api.proxyAliases.get('507f1f77bcf86cd799439022');

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": "http",
    "index": 3000,
    "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"
    }
  }
}

Response 404

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

Create a new proxy alias

POST /api/v1/proxy/aliases

Create a custom domain alias for a container. Provide either a custom alias (3–61 chars, lowercase letters, digits, and hyphens only, cannot start or end with a hyphen) or set alias to null / false to let the system auto-generate a 48-character hex string for maximum obscurity.

Note

Reserved labels are rejected: the exact label "containers", anything equal to "proxy" / "workspaces", or anything starting with "proxy-" / "workspaces-". Distinct labels such as "containers-my-app" and "proxymyapp" are allowed. Aliases must be unique across every container hosted on the same physical server, including containers owned by other tenants — not merely within your own account.

Request Body

Field	Type	Required	Default	Description
container_id	string	Yes	—	Container ID that this alias points to. You must own this container.
alias	string | null | boolean	No	—	Custom alias name (a-z, 0-9, hyphens only, 3-61 chars, cannot start/end with hyphen) OR null / false for an auto-generated 48-char hex.
program	string	Yes	—	Built-in Hoody program ("terminal", "files", "code", "browser", "agent", "display", …) or transport protocol ("http", "https", "ssh"). For an HTTP server you run inside the container, use program: "http" (or "https" for TLS) with the port field.
port	integer	No	—	Target port for "http" / "https" (1–65535). Takes precedence over index and over any port embedded in the program string ("http-3000"). Ignored for built-in Hoody programs.
index	integer	No	—	Instance index, or legacy target port for "http" / "https". Defaults to 1. For a built-in program it selects which running instance to route to.
target_path	string | null	No	—	Base path for routing. Auto-prefixed with / if missing. Max 2048 chars. Pass 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 will be automatically disabled after this date. Pass null for no expiration.
enabled	boolean	No	true	Whether the alias is initially enabled.

cURL

curl -X POST "https://api.hoody.icu/api/v1/proxy/aliases" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "container_id": "507f1f77bcf86cd799439011",
    "alias": "my-app",
    "program": "http",
    "port": 3000,
    "target_path": null,
    "allow_path_override": true
  }'

SDK

const result = await client.api.proxyAliases.create({
  container_id: '507f1f77bcf86cd799439011',
  alias: 'my-app',
  program: 'http',
  port: 3000,
  target_path: null,
  allow_path_override: true,
});

Response 201

{
  "statusCode": 201,
  "message": "Proxy alias created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439022",
    "project_id": "507f1f77bcf86cd799439033",
    "container_id": "507f1f77bcf86cd799439011",
    "alias": "my-app",
    "program": "http",
    "index": 3000,
    "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"
  }
}

Response 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).

Response 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.

Response 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.

Response 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.

Response 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.

Update proxy alias

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

Update an existing proxy alias. Only provided fields will be updated. Renaming an alias renames the file on the server.

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 satisfy the same format and uniqueness rules as creation.
program	string	No	Program or protocol the alias targets.
port	integer	No	Target port for "http" / "https" (1–65535). Preferred over index.
index	integer	No	Instance index, or legacy target port when program is "http" / "https".
target_path	string | null	No	Base path for routing. Set to null to remove the path prefix. Max 2048 chars.
allow_path_override	boolean	No	Whether to allow paths beyond target_path.
expires_at	string | number | null	No	Expiration date (ISO string, Unix timestamp in seconds/ms, or null to remove expiration).
enabled	boolean	No	Whether the alias is enabled.

cURL

curl -X PATCH "https://api.hoody.icu/api/v1/proxy/aliases/507f1f77bcf86cd799439022" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "http",
    "port": 8080,
    "target_path": "/v2"
  }'

SDK

const result = await client.api.proxyAliases.update('507f1f77bcf86cd799439022', {
  program: 'http',
  port: 8080,
  target_path: '/v2',
});

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": "http",
    "index": 8080,
    "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"
  }
}

Response 400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request body"
}

Response 404

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

Response 409

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

Enable or disable proxy alias

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

Temporarily enable or disable a proxy alias without deleting it. Disabled aliases return 404 at their URL but can be re-enabled later.

Caution

If an alias name has become reserved (only possible for aliases created before the name was reserved), a request that would make it serve traffic again is refused. Rename it to a non-reserved alias first, or delete it. Disabling is never refused for that reason.

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.

cURL

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

SDK

const result = await client.api.proxyAliases.setState('507f1f77bcf86cd799439022', { 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": "http",
    "index": 3000,
    "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"
  }
}

Response 404

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

Delete proxy alias

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

Permanently delete a proxy alias and remove its file from the server. The alias URL will immediately return 404.

Parameters

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

cURL

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

SDK

const result = await client.api.proxyAliases.delete('507f1f77bcf86cd799439022');

Response 200

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

Response 404

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