Computers
Section titled “Computers”The Computers API manages Hoody computers across projects. Use these endpoints to list and inspect computers, monitor resource and proxy usage, create or authorize access, update settings and virtualization support, and delete computers. These are control-plane operations served from https://api.hoody.com.
In the Hub, open Computers and select Get a computer to create one. Select a computer to inspect it, or use Rename… and Delete… from its menu.
List computers
Section titled “List computers”GET /api/v1/computers/
Section titled “GET /api/v1/computers/”Returns all computers across all projects for the current user. The endpoint supports pagination, filtering, and sorting without requiring a project scope.
The SDK iterator helper requests one page at a time and yields each returned computer as it is iterated.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
page | query | number | No | Page number for pagination, starting from 1. Default: 1. |
limit | query | number | No | Number of computers to return per page, up to 100. Default: 50. |
sort_by | query | string | No | Field to sort by. Allowed values: "id", "name", "status", "created_at", "updated_at". Default: "created_at". |
sort_order | query | string | No | Sort direction. Allowed values: "asc", "desc". Default: "desc". |
realm_id | query | string | No | Return only computers that belong to this realm. |
runtime | query | string | No | Include live runtime information. Accepts "true", "false", or URL-encoded JSON such as {"displays":true}. An empty JSON object fetches all runtime information. Runtime data may be up to 2 seconds old. |
include_proxy_domains | query | boolean | No | Include the computer’s proxy domains. When true, each computer includes a proxy_domains array. |
include_proxy_permissions | query | boolean | No | Include the computer-level and parent-project-level proxy-permissions documents. These documents can contain authentication credentials, so request them only when needed. Auth tokens also require the resources.proxy_aliases permission. |
include_expired | query | boolean | No | Include computers that expired after server termination. Expired computers are excluded by default. |
include_deleting | query | boolean | No | Include computers currently being deleted. Deleting computers are excluded by default. |
curl --request GET \ --url 'https://api.hoody.com/api/v1/computers/?page=1&limit=50&sort_by=created_at&sort_order=desc' \ --header "Authorization: Bearer $HOODY_TOKEN"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const computers = [];
for await (const computer of client.api.computers.listIterator({ limit: 50, sort_by: 'created_at', sort_order: 'desc'})) { computers.push(computer);}
console.log(computers);Responses
Section titled “Responses”Media type: application/json
{ "statusCode": 200, "message": "Computers retrieved successfully", "data": { "computers": [ { "id": "890abcdef12345678901cdef", "project_id": "67e89abc123def456789abcd", "project_alias": "production", "server_id": "507f1f77bcf86cd799439014", "server_name": "node-example-1", "ssh_hostname": "67e89abc123def456789abcd-890abcdef12345678901cdef-ssh.node-example-1.computers.hoody.com", "name": "web-app-1", "color": "#3B82F6", "computer_image": "debian/13", "ai": true, "hoody_kit": true, "dev_kit": true, "kvm": false, "autostart": true, "ramdisk_scope": "computer", "ramdisk": true, "is_default": false, "status": "running", "failure_reason": null, "environment_vars": {}, "volumes": {}, "comment": "Primary web application computer", "server_expired": false, "created_at": "2026-07-15T10:30:00.000Z", "updated_at": "2026-07-15T10:30:00.000Z", "realm_ids": [], "snapshot_count": 3, "last_used_snapshot": "before-upgrade", "runtime_info": null, "pool_id": null, "proxy_domains": [], "has_proxy_permissions": false, "proxy_permissions_scope": "none", "proxy_permissions_computer_state": "missing", "has_proxy_domains": false, "proxy_domains_count": 0 } ], "pagination": { "total": 1, "page": 1, "limit": 50, "totalPages": 1 } }}Media type: application/json
{ "statusCode": 401, "error": "INVALID_TOKEN", "message": "Invalid authentication token"}| 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. | Complete email verification by clicking the link sent to your inbox, call /auth/resend-verification, or complete a password reset, which also 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 |
Media type: application/json
{ "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 |
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: page must be greater than or equal to 1", "data": [ { "instancePath": "/page", "schemaPath": "#/properties/page/minimum", "keyword": "minimum", "params": { "minimum": 1 }, "message": "must be greater than or equal to 1" } ]}Media type: application/json
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. |
GET /api/v1/projects/{id}/computers
Section titled “GET /api/v1/projects/{id}/computers”Returns the computers in one project. The endpoint supports pagination, filtering, and sorting.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
page | query | number | No | Page number for pagination. |
limit | query | number | No | Number of computers to return per page. Default: 50. |
sort_by | query | string | No | Field to sort by. Allowed values: "id", "name", "status", "created_at", "updated_at". |
sort_order | query | string | No | Sort direction. Allowed values: "asc", "desc". |
runtime | query | string | No | Include live runtime information. Accepts "true", "false", or URL-encoded JSON such as {"displays":true}. An empty JSON object fetches all runtime information. Runtime data may be up to 2 seconds old. |
include_proxy_domains | query | boolean | No | Include the computer’s proxy domains. When true, each computer includes a proxy_domains array. |
include_proxy_permissions | query | boolean | No | Include the computer-level and parent-project-level proxy-permissions documents. These documents can contain authentication credentials, so request them only when needed. Auth tokens also require the resources.proxy_aliases permission. |
include_expired | query | boolean | No | Include computers that expired after server termination. Expired computers are excluded by default. |
include_deleting | query | boolean | No | Include computers currently being deleted. Deleting computers are excluded by default. |
id | path | string | Yes | Unique identifier of the project. |
PROJECT_ID='67e89abc123def456789abcd'
curl --request GET \ --url "https://api.hoody.com/api/v1/projects/${PROJECT_ID}/computers?limit=20&sort_by=name&sort_order=asc" \ --header "Authorization: Bearer $HOODY_TOKEN"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const projectId = '67e89abc123def456789abcd';const computers = [];
for await (const computer of client.api.computers.listByProjectIterator(projectId, { limit: 20, sort_by: 'name', sort_order: 'asc'})) { computers.push(computer);}
console.log(computers);Responses
Section titled “Responses”Media type: application/json
{ "statusCode": 200, "message": "Computers retrieved successfully", "data": { "computers": [ { "id": "890abcdef12345678901cdef", "project_id": "67e89abc123def456789abcd", "project_alias": "production", "server_id": "507f1f77bcf86cd799439014", "server_name": "node-example-1", "ssh_hostname": "67e89abc123def456789abcd-890abcdef12345678901cdef-ssh.node-example-1.computers.hoody.com", "name": "frontend-prod", "color": "#3B82F6", "computer_image": "debian/13", "ai": true, "hoody_kit": true, "dev_kit": true, "kvm": false, "autostart": true, "is_default": false, "status": "running", "failure_reason": null, "environment_vars": {}, "volumes": {}, "comment": "Production frontend server", "created_at": "2026-07-15T10:30:00.000Z", "updated_at": "2026-07-15T14:22:00.000Z", "realm_ids": [], "snapshot_count": 3, "last_used_snapshot": "before-upgrade", "runtime_info": null, "pool_id": null, "proxy_domains": [], "has_proxy_permissions": false, "proxy_permissions_scope": "none", "proxy_permissions_computer_state": "missing", "has_proxy_domains": false, "proxy_domains_count": 0 } ], "pagination": { "total": 1, "page": 1, "limit": 20, "totalPages": 1 } }}Media type: application/json
{ "statusCode": 401, "error": "INVALID_TOKEN", "message": "Invalid authentication token"}| 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. | Complete email verification by clicking the link sent to your inbox, call /auth/resend-verification, or complete a password reset, which also 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 |
Media type: application/json
{ "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 |
Media type: application/json
{ "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 |
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": []}Media type: application/json
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. |
Get and monitor computers
Section titled “Get and monitor computers”GET /api/v1/computers/{id}
Section titled “GET /api/v1/computers/{id}”Returns one computer by ID, including its configuration, server details, status, and optional runtime and proxy information.
Project owners and admins receive an ETag for the computer’s editable settings. A project member does not receive an ETag.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
runtime | query | string | No | Include live runtime information. Accepts "true", "false", or URL-encoded JSON such as {"displays":true}. An empty JSON object fetches all runtime information. Runtime data may be up to 2 seconds old. |
include_proxy_domains | query | boolean | No | Include the computer’s proxy domains. When true, the computer includes a proxy_domains array. |
include_proxy_permissions | query | boolean | No | Include the computer-level and parent-project-level proxy-permissions documents. These documents can contain authentication credentials, so request them only when needed. Auth tokens also require the resources.proxy_aliases permission. |
id | path | string | Yes | Unique identifier of the computer to retrieve. |
COMPUTER_ID='890abcdef12345678901cdef'
curl --request GET \ --url "https://api.hoody.com/api/v1/computers/${COMPUTER_ID}?include_proxy_domains=true" \ --header "Authorization: Bearer $HOODY_TOKEN"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const computerId = '890abcdef12345678901cdef';const computer = await client.api.computers.get(computerId, { include_proxy_domains: true});
console.log(computer);Responses
Section titled “Responses”Media type: application/json
{ "statusCode": 200, "message": "Computer retrieved successfully", "data": { "id": "890abcdef12345678901cdef", "project_id": "67e89abc123def456789abcd", "project_alias": "production", "server_id": "507f1f77bcf86cd799439014", "server_name": "node-example-1", "ssh_hostname": "67e89abc123def456789abcd-890abcdef12345678901cdef-ssh.node-example-1.computers.hoody.com", "name": "web-app-1", "color": "#3B82F6", "computer_image": "debian/13", "ai": true, "hoody_kit": true, "dev_kit": true, "kvm": false, "autostart": true, "ramdisk_scope": "computer", "ramdisk": true, "is_default": false, "status": "running", "failure_reason": null, "environment_vars": {}, "volumes": {}, "comment": "Primary web application computer", "created_at": "2026-07-15T10:30:00.000Z", "updated_at": "2026-07-15T10:30:00.000Z", "realm_ids": [], "snapshot_count": 3, "last_used_snapshot": "before-upgrade", "runtime_info": null, "pool_id": null, "proxy_domains": [], "has_proxy_permissions": false, "proxy_permissions_scope": "none", "proxy_permissions_computer_state": "missing", "has_proxy_domains": false, "proxy_domains_count": 0 }}Media type: application/json
{ "statusCode": 401, "error": "INVALID_TOKEN", "message": "Invalid authentication token"}| 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. | Complete email verification by clicking the link sent to your inbox, call /auth/resend-verification, or complete a password reset, which also 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 |
Media type: application/json
{ "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 |
Media type: application/json
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NOT_FOUND | Computer not found | The requested computer does not exist or you do not have permission to access it. | Verify the computer ID is correct and that you have access to the project it belongs to. |
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": []}Media type: application/json
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. |
GET /api/v1/computers/{id}/proxy-usage
Section titled “GET /api/v1/computers/{id}/proxy-usage”Returns monthly proxied request counts and response bytes for one computer.
Only completed, routed, non-excluded HTTP responses are counted. Forward-proxy and CONNECT egress, direct SSH, raw computer egress, and open WebSocket sessions are not counted. Reports cover live computers only. The totals sum only the documents returned, so they are not comprehensive when coverage_complete is false. Deleted computers are always excluded.
Older months are retained only if they were read before they expired. A month that was not queried in time may be unavailable permanently. A month withdrawn by an ownership change is no longer served.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string | Yes | First month, inclusive, in YYYY-MM format. |
to | query | string | Yes | Last month, inclusive, in YYYY-MM format. The range can contain at most 12 months. |
id | path | string | Yes | Unique identifier of the computer. |
COMPUTER_ID='890abcdef12345678901cdef'
curl --request GET \ --url "https://api.hoody.com/api/v1/computers/${COMPUTER_ID}/proxy-usage?from=2026-06&to=2026-08" \ --header "Authorization: Bearer $HOODY_TOKEN"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const computerId = '890abcdef12345678901cdef';const usage = await client.api.computers.proxy.getUsage(computerId, { from: '2026-06', to: '2026-08'});
console.log(usage);Responses
Section titled “Responses”Media type: application/json
{ "statusCode": 200, "message": "Proxy usage retrieved successfully", "data": { "from": "2026-06", "to": "2026-08", "excludes_deleted_computers": true, "retrieval_complete": true, "coverage_complete": true, "months_capped": false, "totals": { "requests": 1250, "response_bytes": 5242880, "exact": true }, "retention": { "enforced": true, "retained_from": "2026-01-01" }, "sources": [ { "status": "ok", "reader_stale": false } ], "computers": { "890abcdef12345678901cdef": { "2026-06": { "month": "2026-06", "updated": "2026-07-01T00:05:00.000Z", "days": { "2026-06-01": { "requests": 1250, "response_bytes": 5242880, "slots": 24, "active_slots": 8, "kits": { "webview": 1250 }, "slot_ms": 3600000 } }, "totals": { "requests": 1250, "response_bytes": 5242880, "exact": true }, "measurement": { "excluded_kits": [] } } } } }}Media type: application/json
{ "statusCode": 400, "error": "Bad Request", "message": "Invalid parameter value"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
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) |
Media type: application/json
{ "statusCode": 401, "error": "INVALID_TOKEN", "message": "Invalid authentication token"}| 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. | Complete email verification by clicking the link sent to your inbox, call /auth/resend-verification, or complete a password reset, which also 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 |
Media type: application/json
{ "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 |
Media type: application/json
{ "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 |
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": []}Media type: application/json
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. |
Media type: application/json
{ "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 |
Media type: application/json
{ "statusCode": 502, "message": "Partial proxy usage available", "data": { "from": "2026-06", "to": "2026-08", "excludes_deleted_computers": true, "retrieval_complete": false, "coverage_complete": false, "months_capped": false, "totals": { "requests": 1250, "response_bytes": 5242880, "exact": true }, "retention": { "enforced": true, "retained_from": "2026-01-01" }, "sources": [ { "status": "partial", "reader_stale": true } ], "computers": { "890abcdef12345678901cdef": { "2026-06": { "month": "2026-06", "updated": "2026-07-01T00:05:00.000Z", "days": { "2026-06-01": { "requests": 1250, "response_bytes": 5242880, "slots": 24, "active_slots": 8, "kits": { "webview": 1250 }, "slot_ms": 3600000 } }, "totals": { "requests": 1250, "response_bytes": 5242880, "exact": true }, "measurement": { "excluded_kits": [] } } } } }}GET /api/v1/computers/{id}/stats
Section titled “GET /api/v1/computers/{id}/stats”Returns real-time resource statistics for a computer, including CPU, memory, disk, RAM disk, and network metrics.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier of the computer. |
COMPUTER_ID='890abcdef12345678901cdef'
curl --request GET \ --url "https://api.hoody.com/api/v1/computers/${COMPUTER_ID}/stats" \ --header "Authorization: Bearer $HOODY_TOKEN"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const computerId = '890abcdef12345678901cdef';const stats = await client.api.computers.getStats(computerId);
console.log(stats);Responses
Section titled “Responses”Media type: application/json
{ "statusCode": 200, "message": "Computer statistics retrieved successfully", "data": { "id": "507f1f77bcf86cd799439011", "project_id": "507f1f77bcf86cd799439033", "project_name": "Production Environment", "server_name": "node-example-1", "status": "Running", "status_code": 103, "processes": 143, "started_at": "2025-12-03T18:39:53.938688987Z", "cpu": { "usage": 17303605000, "allocated_time": 24000000000, "usage_percent": 0.08, "usage_percent_raw": 72.1 }, "memory": { "usage": 1474666496, "total": 131503332000, "usage_percent": 1.12, "swap_usage": 0, "swap_usage_peak": 0, "usage_peak": 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" }}Media type: application/json
{ "statusCode": 401, "error": "INVALID_TOKEN", "message": "Invalid authentication token"}| 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. | Complete email verification by clicking the link sent to your inbox, call /auth/resend-verification, or complete a password reset, which also 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 |
Media type: application/json
{ "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 |
Media type: application/json
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NOT_FOUND | Computer not found | The requested computer does not exist or you do not have permission to access it. | Verify the computer 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 |
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": []}Media type: application/json
{ "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 |
Create and authorize computers
Section titled “Create and authorize computers”POST /api/v1/projects/{id}/computers
Section titled “POST /api/v1/projects/{id}/computers”Creates a computer in a project. Creation can take several minutes.
After a successful create, a retry with the same Idempotency-Key and body returns 201 for the same computer with its current fields and the Idempotent-Replayed: true header. If the original create failed after it made a computer, the retry returns that error, and data.computer_id names the computer it made. A create that stopped before finishing returns 409 with COMPUTER_CREATE_INTERRUPTED. If the computer has since been deleted, a retry returns 404.
While the original request is still running, a retry waits for up to 20 seconds. It then returns 409 with IDEMPOTENCY_REQUEST_IN_PROGRESS and a Retry-After header. A create that fails before creating a computer releases its key.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier of the project. |
idempotency-key | header | string | No | Makes the create safe to retry. Use 1 to 128 printable characters, such as a UUID. Use a new key for each new computer. A retry with the same key and body receives the first answer. Reusing the key with a different body is refused. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server on which to create the computer. |
name | string | No | Computer name. Must be 3 to 100 characters and contain only letters, digits, hyphens, and underscores. Omit it or use "rand" to generate a name. |
color | string | No | Hexadecimal color such as #FF0000 or FF0000. If omitted, a random color is generated. The prefix is added automatically when missing, and the value is converted to uppercase. |
computer_image | string or null | No | Image to use, up to 255 characters. If null or omitted, the default configured image is used. Distribution shorthand is resolved to its canonical image. |
ai | boolean | No | Whether AI features are enabled. Default: true. |
environment_vars | object | No | Environment variables as string values. Keys must match ^[a-zA-Z_][a-zA-Z0-9_]*$, be at most 128 characters long, and there can be at most 256 properties. Values must contain 1 to 4096 characters. |
ssh_public_key | string or null | No | SSH public key for direct SSH access. Keys must be unique per computer. If omitted, the project default is inherited. |
comment | string or null | No | Optional comment, up to 16,000 characters. |
hoody_kit | boolean | No | Enables all Hoody Kit features. Default: true. |
dev_kit | boolean | No | Enables the development tools. Defaults to true when hoody_kit is true and false when hoody_kit is false, unless explicitly set. This cannot be changed after creation. |
kvm | boolean | No | Enables /dev/kvm passthrough at creation. It is available only on rented or dedicated servers and is rejected on a free server. Default: false. |
dev_kvm | boolean | No | Accepted alias of kvm. If both are sent, they must agree and kvm takes precedence. |
autostart | boolean | No | Whether the computer starts automatically when its server boots. Default: true. |
ramdisk | boolean | No | Whether to mount a RAM disk at /ramdisk. Default: true. |
realm_ids | array | No | Realm IDs to assign to the computer. Each ID must be 24 lowercase hexadecimal characters. |
PROJECT_ID='67e89abc123def456789abcd'SERVER_ID='507f1f77bcf86cd799439014'
curl --request POST \ --url "https://api.hoody.com/api/v1/projects/${PROJECT_ID}/computers" \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: 8d6ec64a-0f39-4db8-9941-4f2eb03e8af2' \ --data '{ "server_id": "507f1f77bcf86cd799439014", "name": "backend-api", "color": "#10B981", "computer_image": "debian/13", "ai": true, "environment_vars": { "NODE_ENV": "production" }, "hoody_kit": true, "dev_kit": true, "kvm": false, "autostart": true, "ramdisk": true }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const projectId = '67e89abc123def456789abcd';const idempotencyKey = '8d6ec64a-0f39-4db8-9941-4f2eb03e8af2';
const computer = await client.api.computers.create(projectId, { server_id: '507f1f77bcf86cd799439014', name: 'backend-api', color: '#10B981', computer_image: 'debian/13', ai: true, environment_vars: { NODE_ENV: 'production' }, hoody_kit: true, dev_kit: true, kvm: false, autostart: true, ramdisk: true}, { idempotencyKey: idempotencyKey});
console.log(computer);Responses
Section titled “Responses”Media type: application/json
{ "statusCode": 201, "message": "Computer created successfully", "data": { "id": "507f1f77bcf86cd799439015", "project_id": "507f1f77bcf86cd799439011", "project_alias": "my-web-app", "server_id": "507f1f77bcf86cd799439014", "server_name": "node-example-1", "name": "backend-api", "color": "#10B981", "computer_image": "debian/13", "ai": true, "hoody_kit": true, "dev_kit": true, "kvm": false, "autostart": true, "status": "creating", "environment_vars": {}, "volumes": {}, "ssh_public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl user@host", "ssh_key_fingerprint": "SHA256:wBF5vmw/82L9++9kd8PEmcEkErv5hBWXC7aJsuXAyh8", "ssh_key_installed_at": "2025-01-15T15:45:00.000Z", "comment": "Backend API server with PostgreSQL connection", "created_at": "2025-01-15T15:45:00.000Z", "updated_at": "2025-01-15T15:45:00.000Z" }}Media type: application/json
{ "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_COMPUTER_NAME | Invalid computer name | Computer name must be 3 to 100 characters and contain only letters, digits, hyphens, and underscores. | Use a valid name between 3 and 100 characters containing only a-z, A-Z, 0-9, -, and _. |
SERVER_COMPUTER_LIMIT | Server computer limit reached | The target server has reached its maximum number of computers. Stopped computers count. Failed, deleted, and deleting computers do not count. If applicable, data.upgrade explains whether to buy a paid subserver with {"kind":"buy_paid_subserver"} or upgrade a subscription with {"kind":"upgrade_subscription","subscription_id":"<id>"}. | Delete a computer on this server, including a stopped computer, or upgrade the server. |
PROJECT_COMPUTER_LIMIT | Project computer limit reached | The target project has reached its owner-configured computer quota. | Delete an existing computer in this project, raise the project quota, or use a different project. |
IDEMPOTENCY_KEY_INVALID | Invalid Idempotency-Key | The Idempotency-Key header is empty, too long, or contains non-printable characters. | Send 1 to 128 printable characters, such as a UUID. |
UPGRADE_REQUIRED | Request uses a retired name | The request uses a retired identifier that has been renamed to the current computer naming, or it comes from a Hoody CLI that is too old for the renamed API. Nothing was changed. | Send the replacement listed in data.renamed, or update the Hoody CLI and SDK with npm i -g hoody-sdk. |
REALM_LIMIT_REACHED | Realm limit reached | The change would add a realm the account does not use yet, and the account already uses as many realms as its limit allows. A realm is in use while one of your projects or computers carries it. data.max is the limit and data.used the realms in use. Nothing was changed. data.used is omitted for a token limited to realms (it counts every realm of the account). | Use a realm the account already has, remove a realm from every project and computer that carries it, or move to a higher limit: accounts that have held a paid server or rented a bare-metal server get more realms. GET /api/v1/realms shows the limit and the count under cap. |
Media type: application/json
{ "statusCode": 401, "error": "INVALID_TOKEN", "message": "Invalid authentication token"}| 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. | Complete email verification by clicking the link sent to your inbox, call /auth/resend-verification, or complete a password reset, which also 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 |
Media type: application/json
{ "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 |
Media type: application/json
{ "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 |
Media type: application/json
{ "statusCode": 409, "error": "COMPUTER_NAME_IN_USE", "message": "Computer name already in use within the project", "data": { "field": "name", "computer_id": "890abcdef12345678901cdef", "status": "running" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NAME_IN_USE | Computer name already in use | A computer with this name already exists in the project. data.computer_id and data.status identify it when available. | If it is the computer you intended to create, use it. Otherwise choose a different name. |
SSH_PUBLIC_KEY_IN_USE | SSH public key already in use | SSH public keys must be unique per computer. A single key cannot be assigned to multiple computers. | Generate a new SSH key pair for this computer, or remove the key from the other computer before reusing it. |
COMPUTER_NAME_GENERATION_FAILED | No free computer name found | No name was given, and every generated name was already used in the project. Nothing was created. | Retry, or provide a computer name. |
SERVER_DELETION_IN_PROGRESS | Target server is being deleted | The server on which the computer would be created is being deleted. Nothing was created. | Retry after deletion finishes, or choose another server. |
PROJECT_SHARE_REVOKE_IN_PROGRESS | Storage share being removed | A project storage share is being removed. Until that operation finishes, computers cannot join or leave the project. | Retry in a few seconds. |
TARGET_SERVER_UNAVAILABLE | Target server no longer available | The selected server became unavailable before setup completed. The computer was not created. | Retry the create request. |
KVM_PROVISIONING_FAILED | KVM could not be set up | KVM could not be configured for the new computer, so the computer was not created. | Retry the create request, or create the computer without KVM. |
KVM_NOT_AVAILABLE | KVM not available on this server | The server does not provide the dedicated hardware required for KVM. Nothing was changed. | Use a server with dedicated hardware, or contact support. |
KVM_HOST_UPGRADE_REQUIRED | Server does not support KVM yet | The server must be upgraded before KVM can be enabled. Nothing was changed. | Retry after the server is upgraded, or contact support. |
KVM_CHANGE_IN_PROGRESS | Another KVM change is running | Another KVM change is in progress on this server. Nothing was changed. | Retry shortly. |
SERVER_BUSY | Server busy | Another change is running on the target server. A refused create changes nothing. | Retry shortly, or choose another server. |
SUBSERVER_OWNER_MISMATCH | Subserver has another owner | A subserver can hold computers only for its owner. Nothing was changed. | Use a server its owner may use, or move or delete the other owner’s computers first. |
IDEMPOTENCY_REQUEST_IN_PROGRESS | Request still in progress | A request with this Idempotency-Key is still being processed. | Retry after the Retry-After delay with the same key and body. |
COMPUTER_CREATE_INTERRUPTED | Computer create interrupted | Computer creation stopped before it finished. data.computer_id identifies the computer that was created. | Check the computer’s status and delete it if it is not needed. Create again with a new Idempotency-Key. |
Media type: application/json
{ "statusCode": 422, "error": "IDEMPOTENCY_KEY_REUSED", "message": "This Idempotency-Key was already used for a different request. Use a new key for a new computer."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
IDEMPOTENCY_KEY_REUSED | Idempotency-Key reused | This Idempotency-Key was already used for a request with a different body, project, or realm. | Use a new key for a new computer. Reuse a key only to retry the same request. |
Media type: application/json
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. |
Media type: application/json
{ "statusCode": 500, "error": "COMPUTER_CREATE_DISPATCH_FAILED", "message": "Computer creation could not be started on its host"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_CREATE_DISPATCH_FAILED | Computer creation could not be started | The create request could not be sent to the server, so nothing was created. The computer’s name, SSH key, and quota slot remain available. | Retry the request. If it continues to fail, try another server or contact support. |
Media type: application/json
{ "statusCode": 503, "error": "COMPUTER_HOST_UNAVAILABLE", "message": "The server for this computer could not be reached right now. Nothing was created. Retry shortly."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_HOST_UNAVAILABLE | Computer server temporarily unavailable | The server could not be reached, so the create request was not sent and nothing was created. The computer’s name, SSH key, and quota slot remain available. | Retry after the number of seconds in the Retry-After header. |
POST /api/v1/computers/{id}/authorize
Section titled “POST /api/v1/computers/{id}/authorize”Issues a signed, portable computer authorization claim.
The computer_claim is an ED25519-signed credential that identifies the user with sub and type, the authorized computer with computerId and projectId, the requesting grant with token_id and scope, and the issue time with iat and exp. For an auth-token caller, token_id is the requesting token’s ID and scope holds its granted permission paths, such as computers.read. For a login session, both fields are null.
An auth token requires both computers.read and computers.actions.exec. The request returns 403 if either permission is missing. A project collaborator requires edit permission. A computer with status failed, deleting, or deleted cannot be authorized and returns 409. A computer that is still being set up returns 409, and an expired computer returns 409 for non-admin callers. A quarantined computer, or one whose owner no longer has access to its server, returns 403 for non-admin callers.
Computer programs can verify the claim offline using Hoody’s public key from GET /api/v1/meta/public-key, without an API round trip during verification. The authorization has a default expiry of 15 minutes, and expires_in gives the exact lifetime in seconds (900 by default). Call this endpoint again to refresh the claim before it expires. A refresh is refused once the caller has lost access.
Computer claims share their wire format, signing key, and verification procedure with the identity claims issued at login. The differences are claim_type "computer" (verifiers must check this to prevent cross-claim confusion), the computer and project fields, and the shorter lifetime.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier of the computer, as 24 hexadecimal characters. |
COMPUTER_ID='890abcdef12345678901cdef'
curl --request POST \ --url "https://api.hoody.com/api/v1/computers/${COMPUTER_ID}/authorize" \ --header "Authorization: Bearer $HOODY_TOKEN"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const computerId = '890abcdef12345678901cdef';const authorization = await client.api.computers.createClaim(computerId);
console.log(authorization);Responses
Section titled “Responses”Media type: application/json
{ "statusCode": 200, "message": "Computer authorization claim issued", "data": { "computer_claim": { "kid": "v1", "payload_b64": "eyJjbGFpbV90eXBlIjoiY29tcHV0ZXIiLCJ...", "signature_hex": "a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4a1b2c3d4" }, "expires_in": 900, "computer_id": "890abcdef12345678901cdef", "project_id": "67e89abc123def456789abcd" }}The X-Hoody-Signature response header uses the format t=<unix_ts>,kid=<keyId>,path=<urlPath>,sig=<128-hex>.
Media type: application/json
{ "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is 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 |
Media type: application/json
{ "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 |
computer_quarantined | Computer held for review | The computer is quarantined for review, so it cannot be authorized. Admins are not refused. | Contact support. |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
Media type: application/json
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NOT_FOUND | Computer not found | The requested computer does not exist or you do not have permission to access it. | Verify the computer ID is correct and that you have access to the project it belongs to. |
Media type: application/json
{ "statusCode": 409, "error": "OPERATION_STATE_CONFLICT", "message": "Operation cannot be performed in the computer's current state"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
OPERATION_STATE_CONFLICT | Computer State Conflict | The operation cannot be performed because the computer is not in the correct state. | Check the computer’s current status and retry when authorization is supported. |
computer_finalizing | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. |
COMPUTER_EXPIRED | Computer has expired | The computer expired when its server ended or was reinstalled, so it cannot be authorized. Admins are not refused. | The computer cannot be operated again. Delete it, then create a new computer. |
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": []}Media type: application/json
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. |
Media type: application/json
{ "statusCode": 503, "error": "SIGNING_NOT_CONFIGURED", "message": "Response signing is not available"}Update and delete computers
Section titled “Update and delete computers”PUT /api/v1/computers/{id}
Section titled “PUT /api/v1/computers/{id}”Updates a computer’s editable settings. PATCH is also accepted with identical behavior.
A ramdisk_scope change that must be applied to the computer before it is saved cannot be combined with If-Match. Send that change without If-Match.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier of the computer to update. |
if-match | header | string | No | The ETag from an earlier GET or PUT. Saves only over the settings named by that tag. Without this header, the update is unconditional. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | Human-readable computer name. It must be unique within the project and can contain up to 100 characters. |
color | string | No | Hexadecimal color such as #FF0000 or FF0000. If omitted, the current color is preserved. The prefix is added automatically when missing, and the value is converted to uppercase. |
ai | boolean | No | Whether AI features are enabled. If omitted, the current value is preserved. |
autostart | boolean | No | Whether the computer starts automatically when its server boots. If omitted, the current value is preserved. |
ramdisk_scope | string | No | RAM disk sharing scope. Allowed values: "computer", "project". |
ramdisk | boolean | No | Whether to mount a RAM disk at /ramdisk. If omitted, the current value is preserved. |
environment_vars | object | No | Environment variables to set as string values. Keys must match ^[a-zA-Z_][a-zA-Z0-9_]*$, be at most 128 characters long, and there can be at most 256 properties. Values must contain 1 to 4096 characters. Computer responses return environment_vars as {}, so read the values with GET /api/v1/computers/{id}/env. |
ssh_public_key | string or null | No | SSH public key for direct SSH access. Keys are globally unique. Set it to null to remove the key. Setting or replacing a key requires the ssh-keys resource permission; removal requires only computer update permission. |
comment | string or null | No | Optional comment, up to 16,000 characters. Set it to null to clear the existing comment. |
realm_ids | array | No | Complete replacement of the computer’s realm membership. Each ID must be 24 lowercase hexadecimal characters. Realm-restricted tokens cannot change realm membership. |
COMPUTER_ID='890abcdef12345678901cdef'
curl --request PUT \ --url "https://api.hoody.com/api/v1/computers/${COMPUTER_ID}" \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header 'Content-Type: application/json' \ --header 'If-Match: "<etag>"' \ --data '{ "name": "web-app-1", "color": "#3B82F6", "ai": true, "autostart": true, "ramdisk": true, "ramdisk_scope": "computer", "environment_vars": { "NODE_ENV": "production" }, "comment": "Primary web application computer" }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const computerId = '890abcdef12345678901cdef';const etag = '"replace-with-current-etag"';
const computer = await client.api.computers.update(computerId, { name: 'web-app-1', color: '#3B82F6', ai: true, autostart: true, ramdisk: true, ramdisk_scope: 'computer', environment_vars: { NODE_ENV: 'production' }, comment: 'Primary web application computer'}, { ifMatch: etag});
console.log(computer);Responses
Section titled “Responses”Media type: application/json
{ "statusCode": 200, "message": "Computer updated successfully", "data": { "id": "890abcdef12345678901cdef", "project_id": "67e89abc123def456789abcd", "project_alias": "production", "server_id": "507f1f77bcf86cd799439014", "server_name": "node-example-1", "ssh_hostname": "67e89abc123def456789abcd-890abcdef12345678901cdef-ssh.node-example-1.computers.hoody.com", "name": "web-app-1", "color": "#3B82F6", "computer_image": "debian/13", "ai": true, "hoody_kit": true, "dev_kit": true, "kvm": false, "autostart": true, "ramdisk_scope": "computer", "ramdisk": true, "is_default": false, "status": "running", "environment_vars": {}, "volumes": {}, "comment": "Primary web application computer", "created_at": "2026-07-15T10:30:00.000Z", "updated_at": "2026-07-15T14:22:00.000Z", "realm_ids": [], "pool_id": null }}The response includes a new ETag for the updated editable settings when the caller is a project owner or admin.
Media type: application/json
{ "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_COMPUTER_NAME | Invalid computer name | Computer name must be 3 to 100 characters and contain only letters, digits, hyphens, and underscores. | Use a valid name between 3 and 100 characters containing only a-z, A-Z, 0-9, -, and _. |
UPGRADE_REQUIRED | Request uses a retired name | The request uses a retired identifier that has been renamed to the current computer naming, or it comes from a Hoody CLI that is too old for the renamed API. Nothing was changed. | Send the replacement listed in data.renamed, or update the Hoody CLI and SDK with npm i -g hoody-sdk. |
REALM_LIMIT_REACHED | Realm limit reached | The change would add a realm the account does not use yet, and the account already uses as many realms as its limit allows. A realm is in use while one of your projects or computers carries it. data.max is the limit and data.used the realms in use. Nothing was changed. data.used is omitted for a token limited to realms (it counts every realm of the account). | Use a realm the account already has, remove a realm from every project and computer that carries it, or move to a higher limit: accounts that have held a paid server or rented a bare-metal server get more realms. GET /api/v1/realms shows the limit and the count under cap. |
Media type: application/json
{ "statusCode": 401, "error": "INVALID_TOKEN", "message": "Invalid authentication token"}| 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. | Complete email verification by clicking the link sent to your inbox, call /auth/resend-verification, or complete a password reset, which also 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 |
Media type: application/json
{ "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 |
Media type: application/json
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NOT_FOUND | Computer not found | The requested computer does not exist or you do not have permission to access it. | Verify the computer 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 |
Media type: application/json
{ "statusCode": 409, "error": "COMPUTER_NAME_IN_USE", "message": "Computer name already in use within the project", "data": { "field": "name", "computer_id": "890abcdef12345678901cdef", "status": "running" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NAME_IN_USE | Computer name already in use | A computer with this name already exists in the project. data.computer_id and data.status identify it when available. | If it is the computer you intended to update, use it. Otherwise choose a different name. |
SSH_PUBLIC_KEY_IN_USE | SSH public key already in use | SSH public keys must be unique per computer. A single key cannot be assigned to multiple computers. | Generate a new SSH key pair for this computer, or remove the key from the other computer before reusing it. |
COMPUTER_QUARANTINED | Computer held for review | The computer was held for review while the request was in flight, so the change was not saved. Part of it may already have reached the computer. | Contact support. |
COMPUTER_CHANGED_DURING_REQUEST | Computer changed during the request | Another request changed the computer while this request was in flight, so this change was not applied. | Read the computer again and retry. |
ENV_REVISION_EXHAUSTED | Environment change limit reached | The computer’s environment has reached its maximum number of changes. Nothing was changed. | Contact support to reset it. |
COMPUTER_NETWORK_POLICY_MISSING | Computer network policy not in force | The computer has no network policy in force, so it cannot be copied, synchronized, restored, or configured to start automatically. Nothing was changed. | Configure the computer’s network with PUT /api/v1/computers/{id}/network, then retry. |
COMPUTER_ACCESS_SUSPENDED | Computer access is suspended | The computer is under an access suspension and must remain stopped, so it cannot be configured to start automatically. Nothing was changed. | Contact support to restore access. |
COMPUTER_EXPIRED | Computer has expired | The computer expired when its server ended or was reinstalled. Lifecycle operations and snapshot restore or delete are refused. Nothing was done. | The computer cannot be operated again. Delete it, then create a new computer. |
Media type: application/json
{ "statusCode": 412, "error": "PRECONDITION_FAILED", "message": "This resource changed since you read it, so nothing was saved."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
PRECONDITION_FAILED | Precondition failed | The conditional write was refused and nothing was written because the resource changed since the version named in If-Match, or it no longer exists. | Read the resource again, apply the change to the current values, and retry with the new ETag in If-Match. |
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": []}Media type: application/json
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. |
PUT /api/v1/computers/{id}/kvm
Section titled “PUT /api/v1/computers/{id}/kvm”Enables or disables hardware virtualization passthrough at /dev/kvm, allowing the computer to run full virtual machines. PATCH is also accepted with identical behavior.
This operation is available only on rented or dedicated servers, never on free-tier servers. The computer must be stopped. Send kvm: true to enable it or kvm: false to disable it. dev_kvm is accepted as an alias of kvm.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier of the computer. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
kvm | boolean | No | Enables or disables /dev/kvm passthrough. The computer must be stopped. |
dev_kvm | boolean | No | Accepted alias of kvm. If both fields are sent, they must agree and kvm takes precedence. |
COMPUTER_ID='890abcdef12345678901cdef'
curl --request PUT \ --url "https://api.hoody.com/api/v1/computers/${COMPUTER_ID}/kvm" \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header 'Content-Type: application/json' \ --data '{ "kvm": true }'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const computerId = '890abcdef12345678901cdef';const computer = await client.api.computers.enableKvm(computerId);
console.log(computer);The SDK also provides:
client.api.computers.enableKvm(id), which setskvmtotrue.client.api.computers.disableKvm(id), which setskvmtofalse.
Both facade methods set the request body themselves and refuse a body containing dev_kvm.
Responses
Section titled “Responses”Media type: application/json
{ "statusCode": 200, "message": "Computer KVM setting updated successfully", "data": { "id": "890abcdef12345678901cdef", "name": "web-app-1", "status": "stopped", "kvm": true }}Media type: application/json
{ "statusCode": 400, "error": "Bad Request", "message": "Invalid request"}Media type: application/json
{ "statusCode": 401, "error": "INVALID_TOKEN", "message": "Invalid authentication token"}| 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. | Complete email verification by clicking the link sent to your inbox, call /auth/resend-verification, or complete a password reset, which also 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 |
Media type: application/json
{ "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 |
Media type: application/json
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NOT_FOUND | Computer not found | The requested computer does not exist or you do not have permission to access it. | Verify the computer 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 |
Media type: application/json
{ "statusCode": 409, "error": "OPERATION_STATE_CONFLICT", "message": "Operation cannot be performed in the computer's current state"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_OPERATION_IN_PROGRESS | Another operation is running on this computer | Another start, stop, setup, or maintenance operation is already in progress. Nothing was done. | Retry in a few seconds. |
OPERATION_STATE_CONFLICT | Computer State Conflict | The operation cannot be performed because the computer is not in the correct state. | Check the computer’s current status. The computer must be stopped for this operation. |
COMPUTER_CHANGED_DURING_REQUEST | Computer changed during the request | Another request changed the computer while this request was in flight, so this change was not applied. | Read the computer again and retry. |
KVM_HOST_UPGRADE_REQUIRED | Server does not support KVM yet | The server must be upgraded before KVM can be enabled. Nothing was changed. | Retry after the server is upgraded, or contact support. |
KVM_NOT_AVAILABLE | KVM not available on this server | The server does not provide the dedicated hardware required for KVM. Nothing was changed. | Use a server with dedicated hardware, or contact support. |
KVM_HOST_STATE_UNKNOWN | KVM support could not be checked | The server’s KVM support could not be read. Nothing was changed. | Retry shortly. |
KVM_CHANGE_IN_PROGRESS | Another KVM change is running | Another KVM change is in progress on this server. Nothing was changed. | Retry shortly. |
KVM_CHANGE_TIMED_OUT | KVM change stopped | The server took too long to answer, so the KVM change was stopped. | Retry the operation. |
COMPUTER_EXPIRED | Computer has expired | The computer expired when its server ended or was reinstalled. Lifecycle operations and snapshot restore or delete are refused. Nothing was done. | The computer cannot be operated again. Delete it, then create a new computer. |
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": []}Media type: application/json
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. |
DELETE /api/v1/computers/{id}
Section titled “DELETE /api/v1/computers/{id}”Deletes a computer. The computer and its data are removed from its server in the background.
When the request succeeds, the computer’s service URLs, including files, terminal, and http-<port>, answer 404 with MAPPING_NOT_FOUND. If Hoody cannot confirm that with the computer’s server, the URLs stop answering when the background removal runs.
A GET of the computer can answer 404 before its service URLs stop answering, usually by under a second. If its server is slow or cannot be reached, the computer can answer 404 until the background removal runs.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier of the computer to delete. |
COMPUTER_ID='890abcdef12345678901cdef'
curl --request DELETE \ --url "https://api.hoody.com/api/v1/computers/${COMPUTER_ID}" \ --header "Authorization: Bearer $HOODY_TOKEN"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const computerId = '890abcdef12345678901cdef';const result = await client.api.computers.delete(computerId);
console.log(result);Responses
Section titled “Responses”Media type: application/json
{ "statusCode": 200, "message": "Computer deleted successfully"}Media type: application/json
{ "statusCode": 401, "error": "INVALID_TOKEN", "message": "Invalid authentication token"}| 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. | Complete email verification by clicking the link sent to your inbox, call /auth/resend-verification, or complete a password reset, which also 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 |
Media type: application/json
{ "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 |
Media type: application/json
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NOT_FOUND | Computer not found | The requested computer does not exist or you do not have permission to access it. | Verify the computer ID is correct and that you have access to the project it belongs to. |
Media type: application/json
{ "statusCode": 409, "error": "OPERATION_STATE_CONFLICT", "message": "Operation cannot be performed in the computer's current state"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
OPERATION_STATE_CONFLICT | Computer State Conflict | The operation cannot be performed because the computer is not in the correct state. | Check the computer’s current status and retry when deletion is supported. |
COMPUTER_OPERATION_IN_PROGRESS | Another operation is running on this computer | Another start, stop, setup, or maintenance operation is already in progress. Nothing was done. | Retry in a few seconds. |
COMPUTER_CHANGED_DURING_REQUEST | Computer changed during the request | Another request changed the computer while this request was in flight, so this change was not applied. | Read the computer again and retry. |
COMPUTER_SERVER_MISSING | Computer has no server | The computer is not linked to a server, so it cannot be removed safely. Nothing was deleted. | Contact support. |
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": []}Media type: application/json
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. |
Media type: application/json
{ "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 |