# Computer Snapshots **Page:** api/computer-snapshots [Download Raw Markdown](./api/computer-snapshots.md) --- # Computer Snapshots Create, restore, alias, and delete snapshots of a computer. Use these endpoints to capture a point-in-time copy of a computer before a change, restore a computer to an earlier state, attach a human-friendly alias to a snapshot, or free snapshot capacity by deleting old copies. All five endpoints are served by the control plane at `https://api.hoody.com` and require a Hoody account token in the `Authorization` header. A computer is addressed by its `id`, and a snapshot by its canonical `name` as returned by the list endpoint. A snapshot's canonical `name` is the sanitized alias when an alias was supplied. Letters, digits, underscores, and hyphens are kept, while leading and trailing hyphens and underscores are stripped. The canonical name is at most 64 characters. Without an alias, or when sanitization leaves nothing, the name is a timestamped `snap-YYYYMMDD-HHMMSS` value. In the Hub, open Computers, select the computer, and open Backups. Choose Take snapshot to create one, Restore on a snapshot to restore it, or its menu for Rename label and Delete. ## List snapshots ### `GET /api/v1/computers/{id}/snapshots` Get all snapshots for a computer. The response includes the snapshot count and the maximum number of snapshots the computer may hold. The whole list is returned in a single response, with no paging. This endpoint takes no request body. ### Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `id` | path | `string` | Yes | Unique identifier of the computer to retrieve snapshots for | ### Response ```bash curl -X GET "https://api.hoody.com/api/v1/computers/890abcdef12345678901cdef/snapshots" \ -H "Authorization: Bearer $HOODY_TOKEN" ``` The SDK helper is an async iterator. It sends one request when iteration begins and yields the snapshots of that response. ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const computerId = '890abcdef12345678901cdef'; for await (const item of client.api.snapshots.listIterator(computerId)) { console.log(item); } ``` Media type: `application/json` The snapshots currently held by the computer. ```json { "statusCode": 200, "message": "Snapshots retrieved successfully", "data": { "computer_id": "507f1f77bcf86cd799439011", "project_id": "507f1f77bcf86cd799439033", "snapshot_count": 2, "max_snapshots": 25, "snapshots": [ { "name": "snap-20250115-103000", "alias": "backup-2025-01-15", "created_at": "2025-01-15T10:30:00.000Z", "last_used_at": "2025-01-15T14:00:00.000Z", "expires_at": "2025-02-15T10:30:00.000Z", "stateful": false, "size": 2147483648 }, { "name": "snap-20250110-080000", "alias": "weekly-backup", "created_at": "2025-01-10T08:00:00.000Z", "last_used_at": null, "expires_at": null, "stateful": false, "size": 1073741824 } ] } } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `message` | `string` | Result message | | `data.computer_id` | `string` | Identifier of the computer the snapshots belong to | | `data.project_id` | `string` | Identifier of the project the computer belongs to | | `data.snapshot_count` | `number` | Number of snapshots the computer currently holds | | `data.max_snapshots` | `number` or null | Maximum snapshots allowed on this computer: 2 on a free server, the plan's `snapshots_per_computer` on a paid subserver, 1000 elsewhere | | `data.snapshots` | array | Snapshot records held by the computer | | `data.snapshots[].name` | `string` | Canonical name of the snapshot | | `data.snapshots[].alias` | `string` or null | Alias assigned to the snapshot, or null when no alias is set | | `data.snapshots[].created_at` | `string` | Timestamp of the snapshot creation | | `data.snapshots[].last_used_at` | `string` or null | Timestamp of the last use of the snapshot, or null when it has not been used | | `data.snapshots[].expires_at` | `string` or null | Timestamp of the snapshot expiry, or null when it does not expire | | `data.snapshots[].stateful` | `boolean` | Whether the snapshot preserves computer state | | `data.snapshots[].size` | `number` | Size of the snapshot in bytes | Media type: `application/json` The computer has no server assigned. ```json { "statusCode": 400, "error": "Bad Request", "message": "Computer does not have a server assigned" } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | Media type: `application/json` The request was not authenticated. ```json { "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required" } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `MISSING_TOKEN` | Authentication token missing | The request carries no `Authorization` header, or the header holds no token | Send an `Authorization` header as `Bearer ` with a sign-in token or an auth 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 sign-in token (JWT) has expired. An expired auth token is refused with `INVALID_TOKEN` instead. | Sign in again, or refresh the 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 or email, or password, is incorrect | Verify your credentials and try again, or use the password reset feature | | `EMAIL_NOT_VERIFIED` | Email not verified | The password is correct but the account's email address is not verified yet. It is only returned after the password has been checked. On the login endpoint the response carries `data.email`, so the client can offer to resend the verification link. HTTP Basic authentication returns it on any operation, without the email. | Complete email verification by clicking the link sent to your inbox, or call `POST /api/v1/auth/resend-verification` to receive a new link, 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` The account is not allowed to perform this action. ```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` No computer has this ID. ```json { "statusCode": 404, "error": "Not Found", "message": "Computer with ID 507f1f77bcf86cd799439011 not found" } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | Media type: `application/json` The request did not match the operation schema, or its JSON body could not be parsed. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must match pattern \"^[0-9a-f]{24}$\"" } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failing check | | `data` | any JSON value | The failing checks, when there are any. For a schema failure, one entry per failing field | Media type: `application/json` The request failed because of an unexpected server-side error. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "An error occurred while getting the snapshots" } ``` ## Create a snapshot ### `POST /api/v1/computers/{id}/snapshots` Create a new snapshot for a computer. ### Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `id` | path | `string` | Yes | Unique identifier of the computer to create snapshot for | ### Request body The request body is required. | Name | Type | Required | Description | |------|------|----------|-------------| | `alias` | `string` | No | User-friendly alias for the snapshot. It is kept as the alias and also becomes the snapshot name after sanitizing. Letters, digits, underscores, and hyphens are kept, while leading and trailing hyphens and underscores are stripped. The sanitized name is at most 64 characters. If sanitizing leaves exactly one character, the request is refused with 400. If it leaves nothing, a timestamped name is used. An alias with control or invisible characters is refused with 400. Maximum length: 100. | | `expiry` | `integer` | No | Expiry in days, from 1 to 3650. Values outside this range are rejected before the snapshot is created. | ```json { "alias": "pre-deployment-backup", "expiry": 30 } ``` ### Response ```bash curl -X POST "https://api.hoody.com/api/v1/computers/890abcdef12345678901cdef/snapshots" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "alias": "pre-deployment-backup", "expiry": 30 }' ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const computerId = '890abcdef12345678901cdef'; const created = await client.api.snapshots.create(computerId, { alias: 'pre-deployment-backup', expiry: 30 }); console.log(created); ``` Media type: `application/json` The snapshot was created. The supplied alias was kept as the alias and, after sanitizing, became the canonical snapshot name. ```json { "statusCode": 201, "message": "Snapshot created successfully", "data": { "computer_id": "507f1f77bcf86cd799439011", "project_id": "507f1f77bcf86cd799439033", "snapshot": { "name": "pre-deployment-backup", "alias": "pre-deployment-backup", "created_at": "2025-01-15T14:55:00.000Z", "last_used_at": null, "expires_at": "2025-02-14T14:55:00.000Z", "stateful": false, "size": 2147483648 } } } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `message` | `string` | Result message | | `data.computer_id` | `string` | Identifier of the computer the snapshot was created on | | `data.project_id` | `string` | Identifier of the project the computer belongs to | | `data.snapshot.name` | `string` | Canonical name of the new snapshot | | `data.snapshot.alias` | `string` or null | Alias supplied for the snapshot, or null when no alias is set | | `data.snapshot.created_at` | `string` | Timestamp of the snapshot creation | | `data.snapshot.last_used_at` | `string` or null | Timestamp of the last use of the snapshot, or null when it has not been used | | `data.snapshot.expires_at` | `string` or null | Timestamp of the snapshot expiry, or null when it does not expire | | `data.snapshot.stateful` | `boolean` | Whether the snapshot preserves computer state | | `data.snapshot.size` | `number` | Size of the snapshot in bytes | Media type: `application/json` The snapshot was not created. The computer already holds the maximum number of snapshots allowed for its server, or the supplied alias cannot be used as a snapshot name. A request body that does not match the schema is answered with 422 `Validation Error` instead. ```json { "statusCode": 400, "error": "COMPUTER_SNAPSHOT_LIMIT", "message": "This computer has reached its snapshot limit (2/2). Delete an existing snapshot before creating a new one.", "data": { "field": "computer_snapshot_limit", "computer_id": "507f1f77bcf86cd799439011", "server_id": "507f1f77bcf86cd799439022", "current_count": 2, "limit": 2 } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `COMPUTER_SNAPSHOT_LIMIT` | Computer snapshot limit reached | The computer already holds the maximum number of snapshots allowed for its server. Computers on free-tier servers are capped lower than those on paid servers and rentals. The applicable limit is returned as `max_snapshots` when listing snapshots. | Delete an existing snapshot on this computer before creating a new one. | | `Bad Request` | Invalid input (VALIDATION_ERROR) | A value passed the request schema but failed a check of this operation. The message names the problem. The response's `error` is `Bad Request`; this code is not sent. A request that does not match the schema is answered with 422 `Validation Error` instead. | Correct the value the message names, then send the request again. | Catalogue error codes: `VALIDATION_ERROR`. | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | | `data.field` | `string` | Field the failure relates to | | `data.computer_id` | `string` | Identifier of the computer | | `data.server_id` | `string` | Identifier of the server the computer runs on | | `data.current_count` | `number` | Number of snapshots the computer currently holds | | `data.limit` | `number` | Maximum number of snapshots allowed on the computer | Media type: `application/json` The request was not authenticated. ```json { "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required" } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `MISSING_TOKEN` | Authentication token missing | The request carries no `Authorization` header, or the header holds no token | Send an `Authorization` header as `Bearer ` with a sign-in token or an auth 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 sign-in token (JWT) has expired. An expired auth token is refused with `INVALID_TOKEN` instead. | Sign in again, or refresh the 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 or email, or password, is incorrect | Verify your credentials and try again, or use the password reset feature | | `EMAIL_NOT_VERIFIED` | Email not verified | The password is correct but the account's email address is not verified yet. It is only returned after the password has been checked. On the login endpoint the response carries `data.email`, so the client can offer to resend the verification link. HTTP Basic authentication returns it on any operation, without the email. | Complete email verification by clicking the link sent to your inbox, or call `POST /api/v1/auth/resend-verification` to receive a new link, 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` The account is not allowed to perform this action. ```json { "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions" } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `computer_quarantined` | Computer held for review | The computer is held for review, so its snapshots cannot be changed. Nothing was changed. | Contact support. | | `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` No computer has this ID. ```json { "statusCode": 404, "error": "Not Found", "message": "Computer with ID 507f1f77bcf86cd799439011 not found" } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | Media type: `application/json` The snapshot was not created because the computer is busy, expired, or otherwise not in a state that allows the operation. ```json { "statusCode": 409, "error": "SNAPSHOT_OPERATION_IN_PROGRESS", "message": "Another snapshot operation may be running for this computer, or the service is temporarily unavailable. Nothing was created; retry shortly.", "data": { "field": "snapshot_lock", "computer_id": "507f1f77bcf86cd799439011" } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `SNAPSHOT_OPERATION_IN_PROGRESS` | Snapshot creation busy | Another snapshot creation may be running for this computer, or snapshot creation is temporarily unavailable. Nothing was created. | Retry after a few seconds. See the `Retry-After` header. | | `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. 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. | | `RESOURCE_ALREADY_EXISTS` | Resource already exists | A resource with this identifier already exists | Use a different identifier or update the existing resource instead | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, is being delivered, is being deleted, or has a change in progress. Computers on it cannot be created, started, stopped, changed, copied, shared, or deleted. `data.reason` is `not_active`, `operation_in_flight`, or `no_subscription`. Nothing was changed. | Retry once the subserver is active again. Renew a held subscription, or wait for the change to finish. | | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | | `data.field` | `string` | Field the failure relates to | | `data.computer_id` | `string` | Identifier of the computer | | `data.server_id` | `string` | Identifier of the server the computer runs on | | `data.reason` | `string` | Reason returned with `SUBSERVER_DORMANT` | Media type: `application/json` The request did not match the operation schema, or its JSON body could not be parsed. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must match pattern \"^[0-9a-f]{24}$\"" } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failing check | | `data` | any JSON value | The failing checks, when there are any. For a schema failure, one entry per failing field | Media type: `application/json` A request limit for this operation was used up. The response carries a `Retry-After` header with the number of seconds to wait. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `Too Many Requests` | 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. The body's `error` is `Too Many Requests`. | Wait the number of seconds in the `Retry-After` header, then try again. | Catalogue error codes: `RATE_LIMIT_EXCEEDED`. | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | Media type: `application/json` The request failed because of an unexpected server-side error. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "An error occurred while creating the snapshot" } ``` Media type: `application/json` The snapshot inventory could not be read, so the request was refused instead of creating a snapshot that might exceed the limit. ```json { "statusCode": 503, "error": "SNAPSHOT_INVENTORY_UNAVAILABLE", "message": "Unable to verify this computer's snapshot inventory. No changes were made.", "data": { "field": "snapshot_inventory", "computer_id": "507f1f77bcf86cd799439011" } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `SNAPSHOT_INVENTORY_UNAVAILABLE` | Snapshot inventory could not be verified | The computer's live snapshot list could not be read, so the snapshot limit could not be checked. The request is refused rather than creating a snapshot that might exceed it. | Retry shortly. If it persists, contact support. | | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | | `data.field` | `string` | Field the failure relates to | | `data.computer_id` | `string` | Identifier of the computer | ## Restore a computer from a snapshot ### `PUT /api/v1/computers/{id}/snapshots/{name}` Restore a computer from a snapshot. The server also accepts `PATCH` for this route, with identical behavior. This endpoint takes no request body. ### Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `id` | path | `string` | Yes | Unique identifier of the computer to restore | | `name` | path | `string` | Yes | The snapshot's canonical name as returned by the list endpoint. For a snapshot created with an alias, this is the sanitized alias: letters, digits, underscores, and hyphens are kept, while leading and trailing hyphens and underscores are stripped. The name is at most 64 characters. Without an alias, or when sanitization leaves nothing, it is a timestamped `snap-YYYYMMDD-HHMMSS` value. | ### Response ```bash curl -X PUT "https://api.hoody.com/api/v1/computers/890abcdef12345678901cdef/snapshots/snap-20250115-103000" \ -H "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 restored = await client.api.snapshots.restore(computerId, 'snap-20250115-103000'); console.log(restored); ``` Media type: `application/json` The computer was restored from the snapshot. ```json { "statusCode": 200, "message": "Computer restored from snapshot successfully", "data": { "success": true, "message": "Snapshot restored." } } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `message` | `string` | Result message | | `data.success` | `boolean` | Whether the restore succeeded | | `data.message` | `string` | Result message of the restore operation | Media type: `application/json` The snapshot name is not valid, or the computer has no server assigned. ```json { "statusCode": 400, "error": "Bad Request", "message": "Computer does not have a server assigned" } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | Media type: `application/json` The request was not authenticated. ```json { "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required" } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `MISSING_TOKEN` | Authentication token missing | The request carries no `Authorization` header, or the header holds no token | Send an `Authorization` header as `Bearer ` with a sign-in token or an auth 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 sign-in token (JWT) has expired. An expired auth token is refused with `INVALID_TOKEN` instead. | Sign in again, or refresh the 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 or email, or password, is incorrect | Verify your credentials and try again, or use the password reset feature | | `EMAIL_NOT_VERIFIED` | Email not verified | The password is correct but the account's email address is not verified yet. It is only returned after the password has been checked. On the login endpoint the response carries `data.email`, so the client can offer to resend the verification link. HTTP Basic authentication returns it on any operation, without the email. | Complete email verification by clicking the link sent to your inbox, or call `POST /api/v1/auth/resend-verification` to receive a new link, 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` The account is not allowed to perform this action. ```json { "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions" } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `computer_quarantined` | Computer held for review | The computer is held for review, so its snapshots cannot be changed. Nothing was changed. | Contact support. | | `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` The computer or the snapshot was not found. When the name in the path is the alias of a snapshot, the message names the snapshot to use instead. ```json { "statusCode": 404, "error": "Not Found", "message": "No snapshot named \"snap-20250110-080000\" on this computer." } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | Media type: `application/json` The restore was refused because the computer is busy, expired, missing a network policy, or otherwise not in a state that allows the operation. ```json { "statusCode": 409, "error": "COMPUTER_NETWORK_POLICY_MISSING", "message": "Computer has no network policy in force and cannot be restored from a snapshot. Configure its network first." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `COMPUTER_NETWORK_POLICY_MISSING` | Computer network policy not in force | The computer has no network policy in force, so it cannot be copied, synced from, restored, or set to start automatically. Nothing was changed. | Configure the computer's network first with `PUT /api/v1/computers/{id}/network`, then retry. | | `COMPUTER_OPERATION_IN_PROGRESS` | Another operation is running on this computer | Another start, stop, setup, or maintenance operation is already in progress on this computer. Nothing was done. | Retry in a few seconds. | | `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. | | `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. | | `OPERATION_STATE_CONFLICT` | Computer State Conflict | The computer must be running, stopped, paused, or failed to be restored from a snapshot. A computer that is being copied, for example, is refused. The message names the current status. Nothing was changed. | Wait until the operation in progress on the computer finishes, then retry. | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, is being delivered, is being deleted, or has a change in progress. Computers on it cannot be created, started, stopped, changed, copied, shared, or deleted. `data.reason` is `not_active`, `operation_in_flight`, or `no_subscription`. Nothing was changed. | Retry once the subserver is active again. Renew a held subscription, or wait for the change to finish. | | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | | `data` | any JSON value | Additional error details | Media type: `application/json` The request did not match the operation schema, or its JSON body could not be parsed. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must match pattern \"^[0-9a-f]{24}$\"" } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failing check | | `data` | any JSON value | The failing checks, when there are any. For a schema failure, one entry per failing field | Media type: `application/json` A request limit for this operation was used up. The response carries a `Retry-After` header with the number of seconds to wait. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `Too Many Requests` | 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. The body's `error` is `Too Many Requests`. | Wait the number of seconds in the `Retry-After` header, then try again. | Catalogue error codes: `RATE_LIMIT_EXCEEDED`. | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | Media type: `application/json` The request failed because of an unexpected server-side error. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "An error occurred while restoring the computer from the snapshot" } ``` ## Update a snapshot alias ### `PUT /api/v1/computers/{id}/snapshots/{name}/alias` Update the alias of an existing snapshot. The server also accepts `PATCH` for this route, with identical behavior. ### Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `id` | path | `string` | Yes | Unique identifier of the computer | | `name` | path | `string` | Yes | The snapshot's canonical name as returned by the list endpoint. For a snapshot created with an alias, this is the sanitized alias: letters, digits, underscores, and hyphens are kept, while leading and trailing hyphens and underscores are stripped. The name is at most 64 characters. Without an alias, or when sanitization leaves nothing, it is a timestamped `snap-YYYYMMDD-HHMMSS` value. | ### Request body The request body is required. | Name | Type | Required | Description | |------|------|----------|-------------| | `alias` | `string` or `null` | Yes | New alias for the snapshot. Set it to `null` to remove the alias. Maximum length: 100. | ```json { "alias": "production-baseline" } ``` ### Response ```bash curl -X PUT "https://api.hoody.com/api/v1/computers/890abcdef12345678901cdef/snapshots/snap-20250115-103000/alias" \ -H "Authorization: Bearer $HOODY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "alias": "production-baseline" }' ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const computerId = '890abcdef12345678901cdef'; const updated = await client.api.snapshots.setAlias(computerId, 'snap-20250115-103000', { alias: 'production-baseline' }); console.log(updated); ``` Media type: `application/json` The alias was updated. ```json { "statusCode": 200, "message": "Snapshot alias updated successfully", "data": { "computer_id": "507f1f77bcf86cd799439011", "project_id": "507f1f77bcf86cd799439033", "snapshot": { "name": "snap-20250115-103000", "alias": "production-baseline", "created_at": "2025-01-15T10:30:00.000Z", "last_used_at": "2025-01-15T14:00:00.000Z", "expires_at": "2025-02-15T10:30:00.000Z", "stateful": false, "size": 2147483648 } } } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `message` | `string` | Result message | | `data.computer_id` | `string` | Identifier of the computer the snapshot belongs to | | `data.project_id` | `string` | Identifier of the project the computer belongs to | | `data.snapshot.name` | `string` | Canonical name of the snapshot | | `data.snapshot.alias` | `string` or null | Alias assigned to the snapshot, or null when no alias is set | | `data.snapshot.created_at` | `string` | Timestamp of the snapshot creation | | `data.snapshot.last_used_at` | `string` or null | Timestamp of the last use of the snapshot, or null when it has not been used | | `data.snapshot.expires_at` | `string` or null | Timestamp of the snapshot expiry, or null when it does not expire | | `data.snapshot.stateful` | `boolean` | Whether the snapshot preserves computer state | | `data.snapshot.size` | `number` | Size of the snapshot in bytes | Media type: `application/json` The snapshot name or alias is not valid, the alias is already used by another snapshot of the computer, or the computer has no server assigned. ```json { "statusCode": 400, "error": "Bad Request", "message": "Computer does not have a server assigned" } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | Media type: `application/json` The request was not authenticated. ```json { "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required" } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `MISSING_TOKEN` | Authentication token missing | The request carries no `Authorization` header, or the header holds no token | Send an `Authorization` header as `Bearer ` with a sign-in token or an auth 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 sign-in token (JWT) has expired. An expired auth token is refused with `INVALID_TOKEN` instead. | Sign in again, or refresh the 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 or email, or password, is incorrect | Verify your credentials and try again, or use the password reset feature | | `EMAIL_NOT_VERIFIED` | Email not verified | The password is correct but the account's email address is not verified yet. It is only returned after the password has been checked. On the login endpoint the response carries `data.email`, so the client can offer to resend the verification link. HTTP Basic authentication returns it on any operation, without the email. | Complete email verification by clicking the link sent to your inbox, or call `POST /api/v1/auth/resend-verification` to receive a new link, 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` The account is not allowed to perform this action. ```json { "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions" } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `computer_quarantined` | Computer held for review | The computer is held for review, so its snapshots cannot be changed. Nothing was changed. | Contact support. | | `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` The computer or the snapshot was not found. When the name in the path is the alias of a snapshot, the message names the snapshot to use instead. ```json { "statusCode": 404, "error": "Not Found", "message": "No snapshot named \"snap-20250110-080000\" on this computer." } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | Media type: `application/json` The alias was not updated because the computer is expired or still being set up. ```json { "statusCode": 409, "error": "COMPUTER_EXPIRED", "message": "Cannot change snapshots of an expired computer. Its server was reinstalled." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `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. | | `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. | | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | | `data` | any JSON value | Additional error details | Media type: `application/json` The request did not match the operation schema, or its JSON body could not be parsed. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must match pattern \"^[0-9a-f]{24}$\"" } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failing check | | `data` | any JSON value | The failing checks, when there are any. For a schema failure, one entry per failing field | Media type: `application/json` A request limit for this operation was used up. The response carries a `Retry-After` header with the number of seconds to wait. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `Too Many Requests` | 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. The body's `error` is `Too Many Requests`. | Wait the number of seconds in the `Retry-After` header, then try again. | Catalogue error codes: `RATE_LIMIT_EXCEEDED`. | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | Media type: `application/json` The request failed because of an unexpected server-side error. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "An error occurred while updating the snapshot alias" } ``` Media type: `application/json` The snapshot inventory could not be read, so the request could not confirm that the target snapshot exists and that the requested alias is not already in use. The alias was not changed. ```json { "statusCode": 503, "error": "SNAPSHOT_INVENTORY_UNAVAILABLE", "message": "Unable to verify this computer's snapshot inventory. No changes were made.", "data": { "field": "snapshot_inventory", "computer_id": "507f1f77bcf86cd799439011" } } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `SNAPSHOT_INVENTORY_UNAVAILABLE` | Snapshot inventory could not be verified | The computer's live snapshot list could not be read, so the request could not confirm that the target snapshot exists and that the requested alias is not already in use. The alias is not changed. | Retry shortly. If it persists, contact support. | | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | | `data.field` | `string` | Field the failure relates to | | `data.computer_id` | `string` | Identifier of the computer | ## Delete a snapshot ### `DELETE /api/v1/computers/{id}/snapshots/{name}` Delete a snapshot. This endpoint takes no request body. ### Parameters | Name | In | Type | Required | Description | |------|----|------|----------|-------------| | `id` | path | `string` | Yes | Unique identifier of the computer | | `name` | path | `string` | Yes | The snapshot's canonical name as returned by the list endpoint. For a snapshot created with an alias, this is the sanitized alias: letters, digits, underscores, and hyphens are kept, while leading and trailing hyphens and underscores are stripped. The name is at most 64 characters. Without an alias, or when sanitization leaves nothing, it is a timestamped `snap-YYYYMMDD-HHMMSS` value. | ### Response ```bash curl -X DELETE "https://api.hoody.com/api/v1/computers/890abcdef12345678901cdef/snapshots/snap-20250110-080000" \ -H "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 deleted = await client.api.snapshots.delete(computerId, 'snap-20250110-080000'); console.log(deleted); ``` Media type: `application/json` The snapshot was deleted. ```json { "statusCode": 200, "message": "Snapshot deleted successfully", "data": { "success": true, "message": "Snapshot deleted." } } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `message` | `string` | Result message | | `data.success` | `boolean` | Whether the snapshot was deleted | | `data.message` | `string` | Result message of the delete operation | Media type: `application/json` The snapshot name is not valid, or the computer has no server assigned. ```json { "statusCode": 400, "error": "Bad Request", "message": "Computer does not have a server assigned" } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | Media type: `application/json` The request was not authenticated. ```json { "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required" } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `MISSING_TOKEN` | Authentication token missing | The request carries no `Authorization` header, or the header holds no token | Send an `Authorization` header as `Bearer ` with a sign-in token or an auth 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 sign-in token (JWT) has expired. An expired auth token is refused with `INVALID_TOKEN` instead. | Sign in again, or refresh the 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 or email, or password, is incorrect | Verify your credentials and try again, or use the password reset feature | | `EMAIL_NOT_VERIFIED` | Email not verified | The password is correct but the account's email address is not verified yet. It is only returned after the password has been checked. On the login endpoint the response carries `data.email`, so the client can offer to resend the verification link. HTTP Basic authentication returns it on any operation, without the email. | Complete email verification by clicking the link sent to your inbox, or call `POST /api/v1/auth/resend-verification` to receive a new link, 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` The account is not allowed to perform this action. ```json { "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions" } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `computer_quarantined` | Computer held for review | The computer is held for review, so its snapshots cannot be changed. Nothing was changed. | Contact support. | | `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` The computer or the snapshot was not found. When the name in the path is the alias of a snapshot, the message names the snapshot to use instead. ```json { "statusCode": 404, "error": "Not Found", "message": "No snapshot named \"snap-20250110-080000\" on this computer." } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | Media type: `application/json` The snapshot was not deleted because the computer is busy, expired, or otherwise not in a state that allows the operation. ```json { "statusCode": 409, "error": "COMPUTER_OPERATION_IN_PROGRESS", "message": "The computer is currently being operated on. Try the snapshot delete again shortly." } ``` | 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 on this computer. Nothing was done. | Retry in a few seconds. | | `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. | | `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. | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, is being delivered, is being deleted, or has a change in progress. Computers on it cannot be created, started, stopped, changed, copied, shared, or deleted. `data.reason` is `not_active`, `operation_in_flight`, or `no_subscription`. Nothing was changed. | Retry once the subserver is active again. Renew a held subscription, or wait for the change to finish. | | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | | `data` | any JSON value | Additional error details | Media type: `application/json` The request did not match the operation schema, or its JSON body could not be parsed. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must match pattern \"^[0-9a-f]{24}$\"" } ``` | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failing check | | `data` | any JSON value | The failing checks, when there are any. For a schema failure, one entry per failing field | Media type: `application/json` A request limit for this operation was used up. The response carries a `Retry-After` header with the number of seconds to wait. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `Too Many Requests` | 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. The body's `error` is `Too Many Requests`. | Wait the number of seconds in the `Retry-After` header, then try again. | Catalogue error codes: `RATE_LIMIT_EXCEEDED`. | Field | Type | Description | |-------|------|-------------| | `statusCode` | `number` | HTTP status code | | `error` | `string` | Error type | | `message` | `string` | Description of the failure | Media type: `application/json` The request failed because of an unexpected server-side error. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "An error occurred while deleting the snapshot" } ```