# Computers **Page:** api/computers [Download Raw Markdown](./api/computers.md) --- # 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 ### `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 | 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. | ```bash 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" ``` ```ts 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 Media type: application/json ```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 ```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 ` | | `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 ```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 ```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 ```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` Returns the computers in one project. The endpoint supports pagination, filtering, and sorting. A project member receives a reduced view containing identity, status, server, and summary flags. It excludes the SSH public key, comment, volumes, environment fields, runtime information, proxy domains, and proxy-permissions documents. For a member, `runtime` and `include_proxy_domains` are ignored, and `include_proxy_permissions` returns `403`. ### 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. | ```bash 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" ``` ```ts 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 Media type: application/json ```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 ```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 ` | | `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 ```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 ```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 ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": [] } ``` Media type: application/json ```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 ### `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 | 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. | ```bash 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" ``` ```ts 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 Media type: application/json ```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 ```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 ` | | `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 ```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 ```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 ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": [] } ``` Media type: application/json ```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` 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 | 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. | ```bash 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" ``` ```ts 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 Media type: application/json ```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 ```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 ```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 ` | | `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 ```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 ```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 ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": [] } ``` Media type: application/json ```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 ```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 ```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` Returns real-time resource statistics for a computer, including CPU, memory, disk, RAM disk, and network metrics. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | `string` | Yes | Unique identifier of the computer. | ```bash COMPUTER_ID='890abcdef12345678901cdef' curl --request GET \ --url "https://api.hoody.com/api/v1/computers/${COMPUTER_ID}/stats" \ --header "Authorization: Bearer $HOODY_TOKEN" ``` ```ts 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 Media type: application/json ```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 ```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 ` | | `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 ```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 ```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 ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": [] } ``` Media type: application/json ```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 ### `POST /api/v1/projects/{id}/computers` Creates a computer in a project. Creation can take several minutes. Send an `Idempotency-Key` header to make the request safe to retry. A retry with the same key and body gets the first request's answer, with the `Idempotent-Replayed: true` header, instead of creating a second computer or failing on the name. The same key with a different body returns `422` with `IDEMPOTENCY_KEY_REUSED`. Keys are retained for 24 hours and belong to the user who sent them. 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 | 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 | 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. | ```bash 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 }' ``` ```ts 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 Media type: application/json ```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 ```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":""}`. | 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 ```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 ` | | `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 ```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 ```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 ```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 ```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 ```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 ```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 ```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` 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](/api/authentication/#identity-claims). 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 | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | `string` | Yes | Unique identifier of the computer, as 24 hexadecimal characters. | ```bash COMPUTER_ID='890abcdef12345678901cdef' curl --request POST \ --url "https://api.hoody.com/api/v1/computers/${COMPUTER_ID}/authorize" \ --header "Authorization: Bearer $HOODY_TOKEN" ``` ```ts 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 Media type: application/json ```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=,kid=,path=,sig=<128-hex>`. Media type: application/json ```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 ` | | `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 ```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 ```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 ```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 ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": [] } ``` Media type: application/json ```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 ```json { "statusCode": 503, "error": "SIGNING_NOT_CONFIGURED", "message": "Response signing is not available" } ``` ## Update and delete computers ### `PUT /api/v1/computers/{id}` Updates a computer's editable settings. `PATCH` is also accepted with identical behavior. Send the `ETag` from an earlier `GET` or `PUT` in the `If-Match` header to avoid overwriting a concurrent change. If the editable settings have changed since the tag was issued, the response is `412` with `PRECONDITION_FAILED`, and nothing is saved. Without `If-Match`, the update is unconditional. 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 | 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 | 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. | ```bash 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: ""' \ --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" }' ``` ```ts 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 Media type: application/json ```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 ```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 ```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 ` | | `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 ```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 ```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 ```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 ```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 ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": [] } ``` Media type: application/json ```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` 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 | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | `string` | Yes | Unique identifier of the computer. | ### 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. | ```bash 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 }' ``` ```ts 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 sets `kvm` to `true`. - `client.api.computers.disableKvm(id)`, which sets `kvm` to `false`. Both facade methods set the request body themselves and refuse a body containing `dev_kvm`. ### Responses Media type: application/json ```json { "statusCode": 200, "message": "Computer KVM setting updated successfully", "data": { "id": "890abcdef12345678901cdef", "name": "web-app-1", "status": "stopped", "kvm": true } } ``` Media type: application/json ```json { "statusCode": 400, "error": "Bad Request", "message": "Invalid request" } ``` Media type: application/json ```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 ` | | `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 ```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 ```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 ```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 ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": [] } ``` Media type: application/json ```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}` 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-`, 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 | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | `string` | Yes | Unique identifier of the computer to delete. | ```bash COMPUTER_ID='890abcdef12345678901cdef' curl --request DELETE \ --url "https://api.hoody.com/api/v1/computers/${COMPUTER_ID}" \ --header "Authorization: Bearer $HOODY_TOKEN" ``` ```ts 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 Media type: application/json ```json { "statusCode": 200, "message": "Computer deleted successfully" } ``` Media type: application/json ```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 ` | | `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 ```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 ```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 ```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 ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: invalid request", "data": [] } ``` Media type: application/json ```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 ```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 |