# Proxy Aliases

**Page:** api/proxy-aliases

[Download Raw Markdown](./api/proxy-aliases.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



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.


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



```json
{
  "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

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

```bash
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



```json
{
  "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"
    }
  }
}
```


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



### SDK

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

```bash
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. |

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

### Response



```json
{
  "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"
  }
}
```


```json
{
  "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). |


```json
{
  "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. |


```json
{
  "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. |


```json
{
  "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. |


```json
{
  "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

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

```bash
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. |

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

### Response



```json
{
  "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"
  }
}
```


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


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


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



### SDK

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

```bash
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. |

```json
{
  "enabled": false
}
```

### Response



```json
{
  "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"
  }
}
```


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



### SDK

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

```bash
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.


This action is irreversible. To temporarily stop an alias from resolving, use the [Enable or disable proxy alias](#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



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


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



### SDK

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

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