Computer Snapshots
Section titled “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.
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
Section titled “List snapshots”GET /api/v1/computers/{id}/snapshots
Section titled “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
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier of the computer to retrieve snapshots for |
Response
Section titled “Response”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.
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.
{ "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.
{ "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.
{ "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 <token> 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.
{ "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.
{ "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.
{ "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.
{ "statusCode": 500, "error": "Internal Server Error", "message": "An error occurred while getting the snapshots"}Create a snapshot
Section titled “Create a snapshot”POST /api/v1/computers/{id}/snapshots
Section titled “POST /api/v1/computers/{id}/snapshots”Create a new snapshot for a computer.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier of the computer to create snapshot for |
Request body
Section titled “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. |
{ "alias": "pre-deployment-backup", "expiry": 30}Response
Section titled “Response”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 }'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.
{ "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.
{ "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.
{ "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 <token> 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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "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
Section titled “Restore a computer from a snapshot”PUT /api/v1/computers/{id}/snapshots/{name}
Section titled “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
Section titled “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
Section titled “Response”curl -X PUT "https://api.hoody.com/api/v1/computers/890abcdef12345678901cdef/snapshots/snap-20250115-103000" \ -H "Authorization: Bearer $HOODY_TOKEN"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const computerId = '890abcdef12345678901cdef';
const restored = await client.api.snapshots.restore(computerId, 'snap-20250115-103000');
console.log(restored);Media type: application/json
The computer was restored from the snapshot.
{ "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.
{ "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.
{ "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 <token> 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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "statusCode": 500, "error": "Internal Server Error", "message": "An error occurred while restoring the computer from the snapshot"}Update a snapshot alias
Section titled “Update a snapshot alias”PUT /api/v1/computers/{id}/snapshots/{name}/alias
Section titled “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
Section titled “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
Section titled “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. |
{ "alias": "production-baseline"}Response
Section titled “Response”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" }'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.
{ "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.
{ "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.
{ "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 <token> 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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "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
Section titled “Delete a snapshot”DELETE /api/v1/computers/{id}/snapshots/{name}
Section titled “DELETE /api/v1/computers/{id}/snapshots/{name}”Delete a snapshot.
This endpoint takes no request body.
Parameters
Section titled “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
Section titled “Response”curl -X DELETE "https://api.hoody.com/api/v1/computers/890abcdef12345678901cdef/snapshots/snap-20250110-080000" \ -H "Authorization: Bearer $HOODY_TOKEN"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const computerId = '890abcdef12345678901cdef';
const deleted = await client.api.snapshots.delete(computerId, 'snap-20250110-080000');
console.log(deleted);Media type: application/json
The snapshot was deleted.
{ "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.
{ "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.
{ "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 <token> 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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "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.
{ "statusCode": 500, "error": "Internal Server Error", "message": "An error occurred while deleting the snapshot"}