Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Proxy Aliases

Section titled “Proxy Aliases”

Proxy aliases let you expose a container behind a short, human-readable label that masks the raw {projectId}-{containerId} host. Instead of sharing https://{projectId}-{containerId}.{server}.containers.hoody.com/, you can hand out https://{alias}.{server}.containers.hoody.com/ and revoke it without touching the container itself. Aliases can target built-in Hoody programs (such as terminal, files, code, browser, agent, display) or any HTTP/HTTPS server you run inside the container on a chosen port.

List proxy aliases

Section titled “List proxy aliases”

GET /api/v1/proxy/aliases

Return every proxy alias owned by the caller, with optional filters by project, container, realm, enabled status, or expiration.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
project_idquerystringNoFilter by project ID
container_idquerystringNoFilter by container ID
realm_idquerystringNoFilter by realm ID. Alternative to using realm subdomain in URL.
enabledquerystringNoFilter by enabled status. Allowed values: "true", "false".
expiredquerystringNoFilter by expiration. Allowed values: "true" (only expired), "false" (only non-expired).

Request

Section titled “Request”
Terminal window
curl -X GET "https://api.hoody.com/api/v1/proxy/aliases?enabled=true&expired=false" \
  -H "Authorization: Bearer <token>"

Response

Section titled “Response”
{
  "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",
        "subserver_name": "user-slice-7",
        "url": "https://my-portfolio.node-sg-sin-1.containers.hoody.com"
      },
      {
        "id": "507f1f77bcf86cd799439055",
        "user_id": "507f1f77bcf86cd799439077",
        "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.com"
      }
    ],
    "count": 2
  }
}

Get proxy alias by ID

Section titled “Get proxy alias by ID”

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

Retrieve a single proxy alias along with its associated project and container records.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesProxy alias ID

Request

Section titled “Request”
Terminal window
curl -X GET "https://api.hoody.com/api/v1/proxy/aliases/507f1f77bcf86cd799439022" \
  -H "Authorization: Bearer <token>"

Response

Section titled “Response”
{
  "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.com",
    "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"
    }
  }
}

Create a new proxy alias

Section titled “Create a new proxy alias”

POST /api/v1/proxy/aliases

Create a new alias for a container you own. The alias field is optional — pass null (or false) and the system generates a 48-character hex label for maximum obscurity. If you supply your own, it must match ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ and be 3–61 characters long.

To point an alias at an HTTP/HTTPS server running inside the container, set program to "http" or "https" and pass the listener port in port. To target a built-in Hoody program such as terminal, just set program (the port is fixed by the program).

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
container_idstringYesContainer ID that this alias points to. You must own this container.
programstringYesThe program or protocol the alias targets. Built-in Hoody programs ("terminal", "files", "code", "browser", "agent", "display", …) or a transport protocol ("http", "https", "ssh").
aliasstring | null | booleanNoCustom alias (3–61 chars, a-z, 0-9, hyphens; cannot start or end with -). Pass null or false to auto-generate a 48-char hex label. Must be unique on the physical server.
portintegerNoTarget port for http/https (1–65535). Takes precedence over index and any port embedded in program.
indexintegerNoInstance index; for http/https it is read as the target port. Prefer port for those. Defaults to 1.
target_pathstringNoBase path prefix. Auto-prefixed with / if missing. Max length 2048.
allow_path_overridebooleanNoWhether paths beyond target_path are allowed. Default: true.
expires_atstringNoISO 8601 expiration date. Alias is auto-disabled after this time.
enabledbooleanNoWhether the alias starts enabled. Default: true.

Request

Section titled “Request”
Terminal window
curl -X POST "https://api.hoody.com/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
  }'

Response

Section titled “Response”
{
  "statusCode": 201,
  "message": "Proxy alias created 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",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-sg-sin-1",
    "subserver_name": "user-slice-7",
    "url": "https://my-app.node-sg-sin-1.containers.hoody.com"
  }
}

Update proxy alias

Section titled “Update proxy alias”

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

Patch one or more fields of an existing alias. Only fields present in the body are touched; omitted fields stay as they were. Renaming an alias changes the URL on the server immediately. Pass target_path: null to remove a path prefix, and expires_at: null to clear an expiration.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesProxy alias ID to update

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
aliasstringNoNew alias name. Same format rules as on create.
programstringNoNew program or protocol.
portintegerNoNew target port for http/https (1–65535).
indexintegerNoNew instance index; for http/https it is read as the target port. Prefer port for those.
target_pathstringNoNew base path prefix. Set to null to remove the prefix.
allow_path_overridebooleanNoWhether to allow paths beyond target_path.
expires_atstring | number | nullNoExpiration (ISO 8601, Unix timestamp seconds/ms, or null to remove).
enabledbooleanNoWhether the alias is enabled.

Request

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

Response

Section titled “Response”
{
  "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.com",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-sg-sin-1",
    "subserver_name": "user-slice-7"
  }
}

Enable or disable proxy alias

Section titled “Enable or disable proxy alias”

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

Toggle a proxy alias on or off without deleting it. Disabled aliases continue to exist in the API but the proxy URL returns 404. If the alias name has since become reserved, a request to re-enable it is refused — rename it first, or delete it. Disabling is never refused for that reason.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesProxy alias ID

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
enabledbooleanYesSet to true to enable, false to disable.

Request

Section titled “Request”
Terminal window
curl -X PATCH "https://api.hoody.com/api/v1/proxy/aliases/507f1f77bcf86cd799439022/state" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Response

Section titled “Response”
{
  "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.com",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-sg-sin-1",
    "subserver_name": "user-slice-7"
  }
}

Delete proxy alias

Section titled “Delete proxy alias”

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

Permanently delete a proxy alias and remove its file from the server. The alias URL returns 404 immediately after this call.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesProxy alias ID to delete

Request

Section titled “Request”
Terminal window
curl -X DELETE "https://api.hoody.com/api/v1/proxy/aliases/507f1f77bcf86cd799439022" \
  -H "Authorization: Bearer <token>"

Response

Section titled “Response”
{
  "statusCode": 200,
  "message": "Proxy alias deleted successfully"
}