Proxy Aliases

Proxy aliases replace the default {projectId}-{containerId}-{service}-{instance} segment of a container URL with a memorable, custom label. Use these endpoints to list, create, inspect, update, toggle, and delete custom aliases for containers you own. Each alias points at a specific program running inside the target container, either a built-in Hoody service (terminal, files, code, browser, agent, display, and so on) or a transport protocol (http, https, ssh) addressed at a TCP port inside the container.

Without an alias, a container URL looks like https://{projectId}-{containerId}-{service}-{instance}.{server}.containers.hoody.com/. With an alias, it becomes https://{alias}.{server}.containers.hoody.com/, hiding the underlying IDs from anyone you share the link with.

Note

Alias names follow two independent uniqueness rules: the name must be free on the container’s physical server (across every tenant hosted there), AND your own account may hold a given name only once across all servers. A different account can reuse your name on a different server; you cannot. The reserved label containers and any label equal to egress or starting with egress- are always rejected.

List proxy aliases

GET /api/v1/proxy/aliases

Returns every proxy alias on your account. Narrow the result set with the project_id, container_id, realm_id, enabled, and expired query parameters.

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	boolean	No	Filter by enabled status
expired	query	boolean	No	Filter by expiration: true = only expired, false = only non-expired

cURL

curl -X GET "https://api.hoody.com/api/v1/proxy/aliases?enabled=true&expired=false" \
  -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 });

for await (const alias of client.api.proxy.aliases.listIterator({ enabled: true, expired: false })) {
  console.log(alias.alias, alias.url);
}

Response 200

{
  "statusCode": 200,
  "message": "Proxy aliases retrieved successfully",
  "data": {
    "aliases": [
      {
        "id": "507f1f77bcf86cd799439022",
        "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-example-1",
        "url": "https://my-portfolio.node-example-1.containers.hoody.com"
      },
      {
        "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-example-1",
        "subserver_name": "user-slice-7",
        "url": "https://c3a8f1b2e4d5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3.node-example-1.containers.hoody.com"
      }
    ],
    "count": 2
  }
}

Response 401

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "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
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session
AUTH_TOKEN_LINEAGE_REVOKED	Parent auth token no longer valid	The auth token was created by another auth token, and that token (or one above it) has been revoked, disabled or has expired, so this one no longer authenticates	Create a new auth token from a valid one, or sign in again
INVALID_CREDENTIALS	Invalid credentials	The provided username/email or password is incorrect	Verify your credentials and try again, or use the password reset feature
EMAIL_NOT_VERIFIED	Email not verified	Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a ‘resend verification email’ action without asking again.	Complete email verification by clicking the link sent to your inbox, or call /auth/resend-verification to receive a new link, or complete a password reset which also implicitly verifies the email.
INVALID_OTP_CODE	Invalid OTP code	The provided 2FA code is incorrect or has expired	Generate a new code from your authenticator app and try again

Response 403

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

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Ask the resource owner to grant you access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

Response 422

Validation Error: the request does not match the operation schema, or its JSON body cannot be parsed. message names each failing check, and data, when present, lists them one entry per failing field.

{
  "statusCode": 422,
  "error": "Validation Error",
  "message": "Validation failed: /name must NOT have fewer than 3 characters"
}

Retrieve a proxy alias

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

Returns the full details of a single proxy alias, including the related project and container records.

Parameters

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

cURL

curl -X GET "https://api.hoody.com/api/v1/proxy/aliases/507f1f77bcf86cd799439022" \
  -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 });

const { data } = await client.api.proxy.aliases.get('507f1f77bcf86cd799439022');

console.log(data.alias, data.url, data.container.name);

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-example-1.containers.hoody.com",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-example-1",
    "subserver_name": "user-slice-7",
    "project": {
      "id": "507f1f77bcf86cd799439033",
      "alias": "production"
    },
    "container": {
      "id": "507f1f77bcf86cd799439011",
      "name": "web-app-1"
    }
  }
}

Response 401

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "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
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session
AUTH_TOKEN_LINEAGE_REVOKED	Parent auth token no longer valid	The auth token was created by another auth token, and that token (or one above it) has been revoked, disabled or has expired, so this one no longer authenticates	Create a new auth token from a valid one, or sign in again
INVALID_CREDENTIALS	Invalid credentials	The provided username/email or password is incorrect	Verify your credentials and try again, or use the password reset feature
EMAIL_NOT_VERIFIED	Email not verified	Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a ‘resend verification email’ action without asking again.	Complete email verification by clicking the link sent to your inbox, or call /auth/resend-verification to receive a new link, or complete a password reset which also implicitly verifies the email.
INVALID_OTP_CODE	Invalid OTP code	The provided 2FA code is incorrect or has expired	Generate a new code from your authenticator app and try again

Response 403

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

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Ask the resource owner to grant you access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

Response 404

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

Response 422

Validation Error: the request does not match the operation schema, or its JSON body cannot be parsed. message names each failing check, and data, when present, lists them one entry per failing field.

{
  "statusCode": 422,
  "error": "Validation Error",
  "message": "Validation failed: /name must NOT have fewer than 3 characters"
}

Create a proxy alias

POST /api/v1/proxy/aliases

Creates a new proxy alias pointing at a program or transport protocol running inside one of your containers. Provide your own custom alias or omit alias to let the system auto-generate a 48-character hex string for maximum obscurity.

Tip

Set alias to null (or omit it entirely) to receive an auto-generated 48-character hex label. Custom aliases must be 3-61 characters, use only lowercase letters, digits, and hyphens, and cannot start or end with a hyphen.

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 or protocol the alias targets. Either a built-in Hoody program (terminal, files, code, browser, agent, display, …) or a transport protocol (http, https, ssh). Use http / https with the port field to reach an HTTP server running on that port inside the container. Must exist in container-programs.json.
alias	string | null | boolean	No	—	Custom alias name (a-z, 0-9, hyphens; 3-61 chars; cannot start/end with hyphen). Pass null or false to receive an auto-generated 48-character hex label.
port	integer	No	—	Target port for the http / https protocol (1-65535). The port your server listens on inside the container. Takes precedence over index and any port embedded in the program string. Ignored for built-in programs.
index	integer	No	—	Instance index (>= 1). For built-in programs, selects which instance to route to. For http / https, it acts as a legacy port field but is overridden by port or any http-<port> embedded in the program.
target_path	string | null	No	—	Landing path served when the alias URL is requested without a path; a query written in it is sent too. With allow_path_override true, a request that carries its own path is forwarded as sent, from the container root (this value is never used as a prefix). With false, it is the only path the alias serves. Auto-prefixed with / if missing. Max 2048 chars.
allow_path_override	boolean	No	true	When false, the alias serves only the root, or target_path itself: once the proxy permissions allow the request, a request to either lands on target_path and any other path, sub-paths and assets included, is refused with 404. A parameter written in target_path always keeps its value; the visitor’s other parameters are passed on, and the method, request body and WebSocket upgrade are forwarded as sent. When true, a root request lands on target_path with its query plus the visitor’s parameters, and a request that carries its own path is forwarded as sent. Either way, anyone who has the link can open the alias: use proxy permissions to restrict who may.
expires_at	string | null	No	—	Optional ISO 8601 timestamp after which the alias is automatically disabled.
enabled	boolean	No	true	Whether the alias is initially enabled.

cURL

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": "/api",
    "allow_path_override": true
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

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

console.log(data.alias, data.url);

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-example-1",
    "subserver_name": "user-slice-7",
    "url": "https://my-app.node-example-1.containers.hoody.com"
  }
}

Response 400

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

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 uses a reserved name/prefix or a shape that would impersonate a canonical container hostname, or fails an alias format rule. (Character-set and length violations are usually reported as a request validation error instead.)	Alias must be 3-61 characters, contain only a-z, 0-9, and hyphens (not at start/end), and avoid reserved infrastructure names.
PORT_REQUIRED	Port Required	An alias for program “http” or “https” was created, or switched from a built-in program, without a port. For these protocols the port is where the alias sends traffic inside the container, so there is no default.	Set port to the port your server listens on (e.g. port 3000), or use the combined program form “http-3000”.

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
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session
AUTH_TOKEN_LINEAGE_REVOKED	Parent auth token no longer valid	The auth token was created by another auth token, and that token (or one above it) has been revoked, disabled or has expired, so this one no longer authenticates	Create a new auth token from a valid one, or sign in again
INVALID_CREDENTIALS	Invalid credentials	The provided username/email or password is incorrect	Verify your credentials and try again, or use the password reset feature
EMAIL_NOT_VERIFIED	Email not verified	Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a ‘resend verification email’ action without asking again.	Complete email verification by clicking the link sent to your inbox, or call /auth/resend-verification to receive a new link, or complete a password reset which also implicitly verifies the email.
INVALID_OTP_CODE	Invalid OTP code	The provided 2FA code is incorrect or has expired	Generate a new code from your authenticator app and try again

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	Ask the resource owner to grant you access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

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.",
  "data": {
    "field": "alias",
    "value": "my-app",
    "scope": "server"
  }
}

Error Code	Title	Description	Resolution
ALIAS_IN_USE	Alias In Use	The requested alias is already in use: taken by any account on the same physical server, or already used by your own account on any server.	Choose a different alias.

Response 422

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "Validation failed",
  "data": [
    { "field": "container_id", "message": "Required" }
  ]
}

Response 503

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Service temporarily unavailable. Please retry."
}

Update a proxy alias

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

Partially updates an existing proxy alias. Only the fields included in the request body are modified. A change is not instant: it usually reaches the alias URL within about 30 seconds and can take longer. Until then the alias keeps its previous behavior, and after a rename the old URL may keep resolving.

Parameters

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

Request Body

Field	Type	Required	Default	Description
alias	string	No	—	New alias name (3-61 chars; a-z, 0-9, hyphens; cannot start/end with hyphen). Subject to the same uniqueness and reserved-name rules as create.
program	string	No	—	New program or protocol the alias targets. Must exist in container-programs.json.
port	integer	No	—	New target port for the http / https protocol (1-65535). Takes precedence over index and any port embedded in the program. Ignored for built-in programs.
index	integer	No	—	New instance index (>= 1). For built-in programs, selects which instance to route to. For http / https, it is the legacy port field and is overridden by port or any http-<port> embedded in the program.
target_path	string | null	No	—	New landing path for root requests, with its own query. With allow_path_override true, requests carrying their own path are forwarded as sent (never a prefix); with false, it is the only path served. Set to null to remove it. Max 2048 chars.
allow_path_override	boolean	No	—	When false, only the root, or target_path itself, is served, as target_path; other paths, sub-paths and assets included, answer 404, and the parameters written in target_path cannot be overridden. When true, a request that carries its own path is forwarded as sent.
expires_at	string | number | null	No	—	New expiration: ISO 8601 string, Unix timestamp, or null to remove.
enabled	boolean	No	—	New enabled state.

cURL

curl -X PATCH "https://api.hoody.com/api/v1/proxy/aliases/507f1f77bcf86cd799439022" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "my-new-name",
    "target_path": "/v2"
  }'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

const { data } = await client.api.proxy.aliases.update('507f1f77bcf86cd799439022', {
  alias: 'my-new-name',
  target_path: '/v2',
});

console.log(data.alias, data.url);

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": true,
    "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-example-1.containers.hoody.com",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-example-1",
    "subserver_name": "user-slice-7"
  }
}

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 uses a reserved name/prefix or a shape that would impersonate a canonical container hostname, or fails an alias format rule. (Character-set and length violations are usually reported as a request validation error instead.)	Alias must be 3-61 characters, contain only a-z, 0-9, and hyphens (not at start/end), and avoid reserved infrastructure names.
PORT_REQUIRED	Port Required	An alias for program “http” or “https” was created, or switched from a built-in program, without a port. For these protocols the port is where the alias sends traffic inside the container, so there is no default.	Set port to the port your server listens on (e.g. port 3000), or use the combined program form “http-3000”.

Response 401

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "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
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session
AUTH_TOKEN_LINEAGE_REVOKED	Parent auth token no longer valid	The auth token was created by another auth token, and that token (or one above it) has been revoked, disabled or has expired, so this one no longer authenticates	Create a new auth token from a valid one, or sign in again
INVALID_CREDENTIALS	Invalid credentials	The provided username/email or password is incorrect	Verify your credentials and try again, or use the password reset feature
EMAIL_NOT_VERIFIED	Email not verified	Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a ‘resend verification email’ action without asking again.	Complete email verification by clicking the link sent to your inbox, or call /auth/resend-verification to receive a new link, or complete a password reset which also implicitly verifies the email.
INVALID_OTP_CODE	Invalid OTP code	The provided 2FA code is incorrect or has expired	Generate a new code from your authenticator app and try again

Response 403

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

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Ask the resource owner to grant you access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

Response 404

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

Response 409

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Alias is already in use.",
  "data": {
    "field": "alias",
    "value": "updated-app-name",
    "scope": "account"
  }
}

Error Code	Title	Description	Resolution
ALIAS_IN_USE	Alias In Use	The requested alias is already in use: taken by any account on the same physical server, or already used by your own account on any server.	Choose a different alias.

Response 422

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "Validation failed",
  "data": [
    { "field": "alias", "message": "must match pattern ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$" }
  ]
}

Response 503

{
  "statusCode": 503,
  "error": "Service Unavailable",
  "message": "Service temporarily unavailable. Please retry."
}

Toggle proxy alias state

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

Enables or disables a proxy alias without deleting it. Disabled aliases stop resolving (they return 404) but can be re-enabled later by sending enabled: true to this same endpoint. The change is not instant: it usually reaches the alias URL within about 30 seconds and can take longer. Until then the alias keeps its previous behavior.

The SDK reaches this operation through two named facade methods, each of which sets enabled for you:

• client.api.proxy.aliases.enable(id) sends enabled: true.
• client.api.proxy.aliases.disable(id) sends enabled: false.

Caution

Re-enabling an alias whose name is now reserved is refused with 409, so rename or delete it instead. Disabling is never refused for that reason. Any alias update, including this one, is also rejected with 409 while the alias’s container is still finalizing a claim.

Parameters

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

Request Body

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

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

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

const { data } = await client.api.proxy.aliases.enable('507f1f77bcf86cd799439022');

console.log(data.alias, data.enabled);

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-example-1.containers.hoody.com",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-example-1",
    "subserver_name": "user-slice-7"
  }
}

Response 401

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "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
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session
AUTH_TOKEN_LINEAGE_REVOKED	Parent auth token no longer valid	The auth token was created by another auth token, and that token (or one above it) has been revoked, disabled or has expired, so this one no longer authenticates	Create a new auth token from a valid one, or sign in again
INVALID_CREDENTIALS	Invalid credentials	The provided username/email or password is incorrect	Verify your credentials and try again, or use the password reset feature
EMAIL_NOT_VERIFIED	Email not verified	Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a ‘resend verification email’ action without asking again.	Complete email verification by clicking the link sent to your inbox, or call /auth/resend-verification to receive a new link, or complete a password reset which also implicitly verifies the email.
INVALID_OTP_CODE	Invalid OTP code	The provided 2FA code is incorrect or has expired	Generate a new code from your authenticator app and try again

Response 403

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

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Ask the resource owner to grant you access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

Response 404

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

Response 409

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Alias name is reserved and cannot be re-activated.",
  "data": {
    "field": "alias",
    "reserved_alias": "containers"
  }
}

Response 422

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "Validation failed",
  "data": [
    { "field": "enabled", "message": "Required" }
  ]
}

Delete a proxy alias

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

Permanently removes the alias record. Removal is not instant: the alias URL usually returns 404 within about 30 seconds and can take longer. Until then the alias keeps its previous behavior.

Parameters

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

cURL

curl -X DELETE "https://api.hoody.com/api/v1/proxy/aliases/507f1f77bcf86cd799439022" \
  -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.proxy.aliases.delete('507f1f77bcf86cd799439022');

Response 200

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

Response 401

{
  "statusCode": 401,
  "error": "MISSING_TOKEN",
  "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
TOKEN_EXPIRED	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session
AUTH_TOKEN_LINEAGE_REVOKED	Parent auth token no longer valid	The auth token was created by another auth token, and that token (or one above it) has been revoked, disabled or has expired, so this one no longer authenticates	Create a new auth token from a valid one, or sign in again
INVALID_CREDENTIALS	Invalid credentials	The provided username/email or password is incorrect	Verify your credentials and try again, or use the password reset feature
EMAIL_NOT_VERIFIED	Email not verified	Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a ‘resend verification email’ action without asking again.	Complete email verification by clicking the link sent to your inbox, or call /auth/resend-verification to receive a new link, or complete a password reset which also implicitly verifies the email.
INVALID_OTP_CODE	Invalid OTP code	The provided 2FA code is incorrect or has expired	Generate a new code from your authenticator app and try again

Response 403

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

Error Code	Title	Description	Resolution
INSUFFICIENT_PERMISSIONS	Insufficient permissions	You do not have the required permissions to perform this action	Ask the resource owner to grant you access
ACCOUNT_BANNED	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

Response 404

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

Response 409

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "container_finalizing: claim is still in progress; retry shortly"
}

Response 422

Validation Error: the request does not match the operation schema, or its JSON body cannot be parsed. message names each failing check, and data, when present, lists them one entry per failing field.

{
  "statusCode": 422,
  "error": "Validation Error",
  "message": "Validation failed: /name must NOT have fewer than 3 characters"
}