Containers

The container endpoints let you list, inspect, create, update, and delete Hoody containers. Use these endpoints to manage the lifecycle of your containers, fetch live resource statistics, and issue offline-verifiable authorization claims for container-aware tooling.

All container hostnames follow the pattern {projectId}-{containerId}-{service}-{instance}.{server}.containers.hoody.com. When concrete IDs are required for examples, both the project ID and the container ID are 24-character lowercase hexadecimal strings.

List containers

`GET /api/v1/containers/`

Returns every container owned by the authenticated user across all projects, with pagination, filtering, and sorting.

Parameters

Name	In	Type	Required	Description
`page`	query	number	No	Page number for pagination. Starts from 1. Default: `1`.
`limit`	query	number	No	Number of containers to return per page. Maximum 100. Default: `50`.
`sort_by`	query	string	No	Field to sort containers by. Allowed: `id`, `name`, `status`, `created_at`, `updated_at`. Default: `"created_at"`.
`sort_order`	query	string	No	Sort direction. Allowed: `asc`, `desc`. Default: `"desc"`.
`realm_id`	query	string	No	Filter by realm ID. Returns only containers belonging to this realm.
`runtime`	query	string	No	Include live runtime information. Accepts `"true"`, `"false"`, or a URL-encoded JSON string such as `{"displays":true}`. An empty object `{}` fetches all info. Results are cached for 2 seconds.
`include_proxy_domains`	query	string	No	When `true`, adds a `proxy_domains` array to each container. Allowed: `"true"`, `"false"`.
`include_proxy_permissions`	query	string	No	When `true`, includes the full proxy-permissions documents (contains credentials). Allowed: `"true"`, `"false"`. Auth tokens additionally require the `resources.proxy_aliases` permission.
`include_prespawn`	query	string	No	Include prespawn containers. Default excludes them. Allowed: `"true"`, `"false"`.
`include_expired`	query	string	No	Include containers expired due to server termination. Default excludes them. Allowed: `"true"`, `"false"`.
`include_deleting`	query	string	No	Include containers currently being deleted. Default excludes them. Allowed: `"true"`, `"false"`.

curl -X GET "https://api.hoody.com/api/v1/containers/?page=1&limit=50&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

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

const result = await client.api.containers.listIterator({ page: 1, limit: 50 });

{
  "statusCode": 200,
  "message": "Containers retrieved successfully",
  "data": {
    "containers": [
      {
        "id": "507f1f77bcf86cd799439011",
        "project_id": "507f1f77bcf86cd799439033",
        "project_alias": "Production Environment",
        "server_id": "507f1f77bcf86cd799439044",
        "server_name": "node-sg-sin-1",
        "subserver_name": "primary",
        "name": "web-app-1",
        "color": "#3B82F6",
        "container_image": "debian/13",
        "ai": true,
        "hoody_kit": true,
        "dev_kit": true,
        "kvm": false,
        "autostart": true,
        "ramdisk": true,
        "ramdisk_scope": "container",
        "prespawn": false,
        "is_default": false,
        "status": "running",
        "environment_vars": {
          "NODE_ENV": "production"
        },
        "volumes": {},
        "ssh_public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...",
        "comment": "Primary web application container",
        "created_at": "2025-01-15T10:30:00.000Z",
        "updated_at": "2025-01-15T10:30:00.000Z",
        "realm_ids": [],
        "snapshot_count": 3,
        "last_used_snapshot": "backup-2025-01-14",
        "pool_id": null
      }
    ],
    "pagination": {
      "total": 5,
      "page": 1,
      "limit": 50,
      "totalPages": 1
    }
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid parameter value"
}

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_PARAMETER_VALUE`	Invalid parameter value	A parameter value is outside the allowed range or format.	Ensure parameter values meet the documented constraints (min/max, format, regex).

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

{
  "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.
`ACCOUNT_BANNED`	Account banned	Your account has been banned and cannot access this resource.	Contact support for information about your account status.

Get a container

`GET /api/v1/containers/{id}`

Returns a single container by its ID, including server metadata, optional runtime info, and optional proxy-permissions documents.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier of the container to retrieve.
`runtime`	query	string	No	Include live runtime information. Accepts `"true"`, `"false"`, or a URL-encoded JSON string such as `{"displays":true}`. An empty object `{}` fetches all info. Results are cached for 2 seconds.
`include_proxy_domains`	query	string	No	When `true`, adds a `proxy_domains` array to the container. Allowed: `"true"`, `"false"`.
`include_proxy_permissions`	query	string	No	When `true`, includes the full proxy-permissions documents (contains credentials). Allowed: `"true"`, `"false"`. Auth tokens additionally require the `resources.proxy_aliases` permission.

curl -X GET "https://api.hoody.com/api/v1/containers/507f1f77bcf86cd799439011?runtime=%7B%22displays%22%3Atrue%7D" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

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

const container = await client.api.containers.get('507f1f77bcf86cd799439011', { runtime: '{"displays":true}' });

{
  "statusCode": 200,
  "message": "Container retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "project_id": "507f1f77bcf86cd799439033",
    "project_alias": "Production Environment",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-sg-sin-1",
    "subserver_name": "primary",
    "name": "web-app-1",
    "color": "#3B82F6",
    "container_image": "debian/13",
    "ai": true,
    "hoody_kit": true,
    "dev_kit": true,
    "kvm": false,
    "autostart": true,
    "ramdisk": true,
    "ramdisk_scope": "container",
    "prespawn": false,
    "is_default": false,
    "status": "running",
    "environment_vars": {
      "NODE_ENV": "production"
    },
    "volumes": {},
    "comment": "Primary web application container",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "realm_ids": [],
    "snapshot_count": 3,
    "last_used_snapshot": "backup-2025-01-14",
    "warnings": [],
    "pool_id": null
  }
}

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

Error Code	Title	Description	Resolution
`INVALID_ID_FORMAT`	Invalid ID format	The provided ID must be a 24-character hexadecimal string.	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f).

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

{
  "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.
`ACCOUNT_BANNED`	Account banned	Your account has been banned and cannot access this resource.	Contact support for information about your account status.

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

Get container statistics

`GET /api/v1/containers/{id}/stats`

Returns real-time resource usage for a container, including CPU, memory, disk, ramdisk, and network metrics. The container must be addressable; CPU and memory stats are null when the container is stopped.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier of the container.

curl -X GET "https://api.hoody.com/api/v1/containers/507f1f77bcf86cd799439011/stats" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

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

const stats = await client.api.containers.getStats('507f1f77bcf86cd799439011');

{
  "statusCode": 200,
  "message": "Container statistics retrieved successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "project_id": "507f1f77bcf86cd799439033",
    "project_name": "Production Environment",
    "server_name": "node-sg-sin-1",
    "subserver_name": "primary",
    "status": "Running",
    "status_code": 103,
    "processes": 143,
    "started_at": "2025-12-03T18:39:53.938688987Z",
    "cpu": {
      "usage": 17303605000,
      "allocated_time": 24000000000,
      "usage_percent": 72.1
    },
    "memory": {
      "usage": 1474666496,
      "total": 131503332000,
      "usage_percent": 1.12,
      "swap_usage": 0,
      "swap_usage_peak": 0,
      "usage_peak": 0
    },
    "ramdisk": {
      "scope": "container",
      "shared_pool_maximum": 536870912,
      "capacity_reserved": false,
      "usage": {
        "private": 4096,
        "secrets": 0
      }
    },
    "disk": {
      "root": {
        "total": 0,
        "usage": 11081670656
      }
    },
    "network": [
      {
        "interface": "eth0",
        "addresses": [
          {
            "address": "10.10.0.122",
            "family": "inet",
            "netmask": "30",
            "scope": "global"
          }
        ],
        "counters": {
          "bytes_received": 1098069936,
          "bytes_sent": 16777319,
          "packets_received": 346440,
          "packets_sent": 242010,
          "errors_received": 0,
          "errors_sent": 0,
          "packets_dropped_inbound": 0,
          "packets_dropped_outbound": 0
        },
        "state": "up",
        "type": "broadcast"
      }
    ],
    "processing_time": "3ms"
  }
}

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

Error Code	Title	Description	Resolution
`INVALID_ID_FORMAT`	Invalid ID format	The provided ID must be a 24-character hexadecimal string.	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f).

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

{
  "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.
`ACCOUNT_BANNED`	Account banned	Your account has been banned and cannot access this resource.	Contact support for information about your account status.
`RESOURCE_ACCESS_DENIED`	Resource access denied	You do not have permission to access this specific resource.	Ensure you own this resource or have been granted access by the owner.

{
  "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.
`RESOURCE_NOT_FOUND`	Resource not found	The requested resource does not exist or has been deleted.	Verify the resource ID and ensure it exists.

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Error Code	Title	Description	Resolution
`INTERNAL_SERVER_ERROR`	Internal server error	An unexpected error occurred on the server.	Try again later, or contact support if the problem persists.
`EXTERNAL_SERVICE_ERROR`	External service error	A required external service is unavailable or returned an error.	Try again later when the external service is available.

List containers for a project

`GET /api/v1/projects/{id}/containers`

Returns every container belonging to the specified project, with pagination, filtering, and sorting.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Project ID.
`page`	query	number	No	Page number for pagination. Starts from 1.
`limit`	query	number	No	Number of containers to return per page. Maximum 100. Default: `50`.
`sort_by`	query	string	No	Field to sort containers by. Allowed: `id`, `name`, `status`, `created_at`, `updated_at`.
`sort_order`	query	string	No	Sort direction. Allowed: `asc`, `desc`.
`runtime`	query	string	No	Include live runtime information. Accepts `"true"`, `"false"`, or a URL-encoded JSON string such as `{"displays":true}`. An empty object `{}` fetches all info. Results are cached for 2 seconds.
`include_proxy_domains`	query	string	No	When `true`, adds a `proxy_domains` array to each container. Allowed: `"true"`, `"false"`.
`include_proxy_permissions`	query	string	No	When `true`, includes the full proxy-permissions documents (contains credentials). Allowed: `"true"`, `"false"`. Auth tokens additionally require the `resources.proxy_aliases` permission.
`include_prespawn`	query	string	No	Include prespawn containers. Default excludes them. Allowed: `"true"`, `"false"`.
`include_deleting`	query	string	No	Include containers currently being deleted. Default excludes them. Allowed: `"true"`, `"false"`.

curl -X GET "https://api.hoody.com/api/v1/projects/507f1f77bcf86cd799439011/containers?page=1&limit=20" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

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

const containers = await client.api.containers.listByProjectIterator('507f1f77bcf86cd799439011', { page: 1, limit: 20 });

{
  "statusCode": 200,
  "message": "Containers retrieved successfully",
  "data": {
    "containers": [
      {
        "id": "507f1f77bcf86cd799439013",
        "project_id": "507f1f77bcf86cd799439011",
        "project_alias": "my-web-app",
        "server_id": "507f1f77bcf86cd799439014",
        "server_name": "node-us-nyc-1",
        "subserver_name": "primary",
        "name": "frontend-prod",
        "color": "#3B82F6",
        "container_image": "debian/13",
        "ai": true,
        "hoody_kit": true,
        "dev_kit": true,
        "kvm": false,
        "autostart": true,
        "prespawn": false,
        "status": "running",
        "environment_vars": {
          "NODE_ENV": "production",
          "PORT": "3000"
        },
        "volumes": {},
        "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl user@host",
        "comment": "Production frontend server",
        "created_at": "2025-01-15T10:30:00.000Z",
        "updated_at": "2025-01-15T14:22:00.000Z",
        "realm_ids": [],
        "snapshot_count": 3,
        "last_used_snapshot": "before-upgrade",
        "pool_id": null,
        "proxy_domains": []
      }
    ],
    "pagination": {
      "total": 42,
      "page": 1,
      "limit": 20,
      "totalPages": 3
    }
  }
}

{
  "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_ID_FORMAT`	Invalid ID format	The provided ID must be a 24-character hexadecimal string.	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f).

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

{
  "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.
`ACCOUNT_BANNED`	Account banned	Your account has been banned and cannot access this resource.	Contact support for information about your account status.

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

Error Code	Title	Description	Resolution
`RESOURCE_NOT_FOUND`	Resource not found	The requested resource does not exist or has been deleted.	Verify the resource ID and ensure it exists.

Authorize container access

`POST /api/v1/containers/{id}/authorize`

Issues a signed, portable container authorization claim. The returned container_claim is an ED25519-signed credential that proves the identity of the user (sub, type), the authorized container (containerId, projectId), and when Hoody issued the authorization (iat, exp).

Container programs can verify this claim offline using Hoody’s public key from GET /api/v1/meta/public-key — no API round-trip is needed during verification. Claims expire after HOODY_CONTAINER_CLAIM_EXPIRES_IN (default 6 hours). Clients should re-call this endpoint to refresh before expiry.

The response also carries an X-Hoody-Signature header in the format t=<unix_ts>,kid=<keyId>,path=<urlPath>,sig=<128-hex> so the entire response body can be independently verified.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID (24-char hex).

curl -X POST "https://api.hoody.com/api/v1/containers/507f1f77bcf86cd799439011/authorize" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

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

const claim = await client.api.containers.authorize('507f1f77bcf86cd799439011');

{
  "statusCode": 200,
  "message": "Container authorization claim issued",
  "data": {
    "container_claim": {
      "kid": "v1",
      "payload_b64": "eyJjbGFpbV90eXBlIjoiY29udGFpbmVyIiwi...",
      "signature_hex": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"
    },
    "expires_in": 21600,
    "container_id": "507f1f77bcf86cd799439011",
    "project_id": "507f1f77bcf86cd799439033"
  }
}

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

Error Code	Title	Description	Resolution
`INVALID_ID_FORMAT`	Invalid ID format	The provided ID must be a 24-character hexadecimal string.	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f).

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

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

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

{
  "statusCode": 503,
  "error": "SIGNING_NOT_CONFIGURED",
  "message": "Response signing is not configured on this API instance"
}

Create a container

`POST /api/v1/projects/{id}/containers`

Creates a new container in the specified project. The container is provisioned on the server named in server_id and enters the creating lifecycle state.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Project ID.

Request Body

Name	Type	Required	Description
`server_id`	string	Yes	Server on which to provision the container.
`name`	string	No	Container name. 3-100 characters, alphanumeric with hyphens and underscores. Use `"rand"` to generate a random name.
`color`	string	No	HEX color (e.g. `#FF0000` or `FF0000`). The `#` prefix is added if missing.
`container_image`	string	No	Container image. Shorthand such as `"debian"` or `"debian-13"` is resolved to the canonical image.
`ai`	boolean	No	Enable AI features. Default: `true`.
`environment_vars`	object	No	Environment variables as key-value string pairs. Maximum 200 keys; each value up to 65536 characters.
`ssh_public_key`	string	No	SSH public key for container access. Must be unique per container. Inherits from project defaults if omitted.
`comment`	string	No	Optional comment, up to 16000 characters.
`hoody_kit`	boolean	No	Enable the Hoody Kit bundle. Default: `true`.
`dev_kit`	boolean	No	Enable dev_kit development tools. Cannot be updated after creation.
`kvm`	boolean	No	Enable `/dev/kvm` passthrough. Rentable dedicated servers only — never free tier. Default: `false`.
`dev_kvm`	boolean	No	Alias of `kvm`. If both are sent, `kvm` wins and both must agree.
`autostart`	boolean	No	Start automatically on host boot. Default: `true`.
`ramdisk`	boolean	No	Mount a ramdisk at `/ramdisk`. Default: `true`.
`cache`	boolean	No	Use cached images during creation. Default: `true`.
`cache_image`	boolean	No	Force creation of a new cached image. Admin-only. Default: `false`.
`prespawn`	boolean	No	Internal. Not user-settable. `true` is rejected (403); `false` is accepted. Default: `false`.
`bypass_prespawn`	boolean	No	Bypass prespawn container claiming and create a fresh container. Default: `false`.
`realm_ids`	array	No	Realm IDs to assign the container to. Merged with the realm of the subdomain when creating from a realm subdomain.

curl -X POST "https://api.hoody.com/api/v1/projects/507f1f77bcf86cd799439011/containers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "507f1f77bcf86cd799439014",
    "name": "backend-api",
    "container_image": "debian/13",
    "environment_vars": {
      "DATABASE_URL": "postgresql://user:pass@db:5432/app",
      "REDIS_URL": "redis://cache:6379"
    },
    "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl user@host",
    "comment": "Backend API server with PostgreSQL connection"
  }'

import { HoodyClient } from 'hoody-sdk';

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

const container = await client.api.containers.create('507f1f77bcf86cd799439011', {
  server_id: '507f1f77bcf86cd799439014',
  name: 'backend-api',
  container_image: 'debian/13',
  environment_vars: {
    DATABASE_URL: 'postgresql://user:pass@db:5432/app',
    REDIS_URL: 'redis://cache:6379'
  },
  ssh_public_key: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl user@host',
  comment: 'Backend API server with PostgreSQL connection'
});

{
  "statusCode": 201,
  "message": "Container created successfully",
  "data": {
    "id": "507f1f77bcf86cd799439015",
    "project_id": "507f1f77bcf86cd799439011",
    "project_alias": "my-web-app",
    "server_id": "507f1f77bcf86cd799439014",
    "server_name": "node-us-nyc-1",
    "subserver_name": "primary",
    "name": "backend-api",
    "color": "#10B981",
    "container_image": "debian/13",
    "ai": true,
    "hoody_kit": true,
    "dev_kit": true,
    "kvm": false,
    "autostart": true,
    "prespawn": false,
    "status": "provisioning",
    "environment_vars": {
      "DATABASE_URL": "postgresql://user:pass@db:5432/app",
      "REDIS_URL": "redis://cache:6379"
    },
    "volumes": {},
    "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl user@host",
    "comment": "Backend API server with PostgreSQL connection",
    "created_at": "2025-01-15T15:45:00.000Z",
    "updated_at": "2025-01-15T15:45:00.000Z",
    "realm_ids": []
  }
}

{
  "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_ID_FORMAT`	Invalid ID format	The provided ID must be a 24-character hexadecimal string.	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f).
`INVALID_CONTAINER_NAME`	Invalid container name	Container name must be 3-100 characters, alphanumeric with hyphens and underscores.	Use a valid name between 3 and 100 characters containing only `a-z`, `A-Z`, `0-9`, `-`, and `_`.
`SERVER_CONTAINER_LIMIT`	Server container limit reached	The target server is at its maximum number of live containers (explicit `max_containers`, or the free-tier default).	Delete an existing container on this server, or create the container on a different server.
`PROJECT_CONTAINER_LIMIT`	Project container limit reached	The target project is at its owner-configured container quota (`projects.max_containers`). Prespawn containers are excluded from this quota.	Delete an existing container in this project, raise the project quota, or use a different project.

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

{
  "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.
`ACCOUNT_BANNED`	Account banned	Your account has been banned and cannot access this resource.	Contact support for information about your account status.

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

Error Code	Title	Description	Resolution
`RESOURCE_NOT_FOUND`	Resource not found	The requested resource does not exist or has been deleted.	Verify the resource ID and ensure it exists.

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Container name already in use within the project"
}

Error Code	Title	Description	Resolution
`CONTAINER_NAME_IN_USE`	Container name already in use	A container with this name already exists in the project.	Choose a different name for your container.
`SSH_PUBLIC_KEY_IN_USE`	SSH public key already in use	SSH public keys must be unique per container because the key is used to route SSH connections.	Generate a new SSH key pair for this container, or remove the key from the other container before reusing it.

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "Quota exceeded"
}

Error Code	Title	Description	Resolution
`QUOTA_EXCEEDED`	Quota exceeded	You have exceeded your quota for this resource type.	Delete unused resources or upgrade your plan for higher limits.

Update a container

`PUT /api/v1/containers/{id}`

Updates mutable fields on a container. Omitted fields are preserved. dev_kit cannot be updated after creation. Container edits on expired containers are rejected.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier of the container to update.

Request Body

Name	Type	Required	Description
`name`	string	No	Human-readable name. 1-100 characters. Must be unique within the project.
`color`	string	No	HEX color (e.g. `#FF0000` or `FF0000`). The `#` prefix is added if missing.
`ai`	boolean	No	Whether AI features are enabled. Preserved if omitted.
`autostart`	boolean	No	Whether the container starts automatically on host boot. Preserved if omitted.
`ramdisk_scope`	string	No	Sharing scope for `/ramdisk`. Allowed: `container`, `project`. `project` is refused when the project has other members.
`ramdisk`	boolean	No	Whether to mount a ramdisk at `/ramdisk`. Preserved if omitted.
`environment_vars`	object	No	Environment variables as key-value pairs. Maximum 200 keys; each value up to 65536 characters.
`ssh_public_key`	string \| null	No	SSH public key. Re-sending the same key is a no-op. Set to `null` to clear or inherit from project defaults.
`comment`	string \| null	No	Optional comment, up to 16000 characters. Set to `null` to clear.
`realm_ids`	array	No	Realm membership. Only unrestricted tokens and admins can modify realm membership.

curl -X PUT "https://api.hoody.com/api/v1/containers/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-app-1-renamed",
    "color": "#10B981",
    "comment": "Renamed for the v2 release",
    "environment_vars": {
      "NODE_ENV": "staging"
    }
  }'

import { HoodyClient } from 'hoody-sdk';

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

const container = await client.api.containers.update('507f1f77bcf86cd799439011', {
  name: 'web-app-1-renamed',
  color: '#10B981',
  comment: 'Renamed for the v2 release',
  environment_vars: {
    NODE_ENV: 'staging'
  }
});

{
  "statusCode": 200,
  "message": "Container updated successfully",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "project_id": "507f1f77bcf86cd799439033",
    "project_alias": "Production Environment",
    "server_id": "507f1f77bcf86cd799439044",
    "server_name": "node-sg-sin-1",
    "subserver_name": "primary",
    "name": "web-app-1-renamed",
    "color": "#10B981",
    "container_image": "debian/13",
    "ai": true,
    "hoody_kit": true,
    "dev_kit": true,
    "kvm": false,
    "autostart": true,
    "ramdisk": true,
    "ramdisk_scope": "container",
    "prespawn": false,
    "is_default": false,
    "status": "running",
    "environment_vars": {
      "NODE_ENV": "staging"
    },
    "volumes": {},
    "comment": "Renamed for the v2 release",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T16:00:00.000Z",
    "realm_ids": [],
    "pool_id": null
  }
}

{
  "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_ID_FORMAT`	Invalid ID format	The provided ID must be a 24-character hexadecimal string.	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f).
`INVALID_CONTAINER_NAME`	Invalid container name	Container name must be 3-100 characters, alphanumeric with hyphens and underscores.	Use a valid name between 3 and 100 characters containing only `a-z`, `A-Z`, `0-9`, `-`, and `_`.

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

{
  "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.
`ACCOUNT_BANNED`	Account banned	Your account has been banned and cannot access this resource.	Contact support for information about your account status.
`OPERATION_NOT_PERMITTED_ON_EXPIRED`	Operation Not Permitted on Expired Container	This operation cannot be performed because the container has expired due to server termination.	The container is in a read-only state. No further operations are allowed. Please create a new container.

{
  "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.
`RESOURCE_NOT_FOUND`	Resource not found	The requested resource does not exist or has been deleted.	Verify the resource ID and ensure it exists.

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Container name already in use within the project"
}

Error Code	Title	Description	Resolution
`CONTAINER_NAME_IN_USE`	Container name already in use	A container with this name already exists in the project.	Choose a different name for your container.
`SSH_PUBLIC_KEY_IN_USE`	SSH public key already in use	SSH public keys must be unique per container because the key is used to route SSH connections.	Generate a new SSH key pair for this container, or remove the key from the other container before reusing it.

Toggle /dev/kvm

`PUT /api/v1/containers/{id}/kvm`

Enables or disables /dev/kvm passthrough so the container can run full virtual machines. Available on rented or dedicated (bare-metal) servers only — never on free-tier servers. The container must be stopped. Send kvm: true to enable or kvm: false to disable. dev_kvm is accepted as an alias of kvm.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier of the container.

Request Body

Name	Type	Required	Description
`kvm`	boolean	No	Enable (`true`) or disable (`false`) `/dev/kvm` passthrough.
`dev_kvm`	boolean	No	Alias of `kvm`. If both are sent, `kvm` wins and both must agree.

curl -X PUT "https://api.hoody.com/api/v1/containers/507f1f77bcf86cd799439011/kvm" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "kvm": true
  }'

import { HoodyClient } from 'hoody-sdk';

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

const result = await client.api.containers.setContainerKvm('507f1f77bcf86cd799439011', {
  kvm: true
});

{
  "statusCode": 200,
  "message": "Container KVM setting updated",
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "name": "web-app-1",
    "status": "stopped",
    "kvm": true
  }
}

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

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

{
  "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.
`RESOURCE_NOT_FOUND`	Resource not found	The requested resource does not exist or has been deleted.	Verify the resource ID and ensure it exists.

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Container must be stopped to change KVM"
}

Delete a container

`DELETE /api/v1/containers/{id}`

Deletes a container. The container must be in a state that allows deletion. Expired containers cannot be deleted.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Unique identifier of the container to delete.

curl -X DELETE "https://api.hoody.com/api/v1/containers/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

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

await client.api.containers.delete('507f1f77bcf86cd799439011');

{
  "statusCode": 200,
  "message": "Container deleted successfully"
}

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

Error Code	Title	Description	Resolution
`INVALID_ID_FORMAT`	Invalid ID format	The provided ID must be a 24-character hexadecimal string.	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f).

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

{
  "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.
`ACCOUNT_BANNED`	Account banned	Your account has been banned and cannot access this resource.	Contact support for information about your account status.
`OPERATION_NOT_PERMITTED_ON_EXPIRED`	Operation Not Permitted on Expired Container	This operation cannot be performed because the container has expired due to server termination.	The container is in a read-only state. No further operations are allowed. Please create a new container.

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

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Resource is currently in use"
}

Error Code	Title	Description	Resolution
`RESOURCE_IN_USE`	Resource in use	This resource cannot be modified or deleted because it is currently in use.	Stop using the resource or remove dependent resources first.
`OPERATION_STATE_CONFLICT`	Container State Conflict	The operation cannot be performed because the container is not in the correct state.	Check the container’s current status. For example, a container must be stopped to be started.

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Error Code	Title	Description	Resolution
`INTERNAL_SERVER_ERROR`	Internal server error	An unexpected error occurred on the server.	Try again later, or contact support if the problem persists.
`EXTERNAL_SERVICE_ERROR`	External service error	A required external service is unavailable or returned an error.	Try again later when the external service is available.