Computer Operations & Lifecycle
Section titled “Computer Operations & Lifecycle”The Computer Operations and Lifecycle endpoints control a computer’s runtime state and expose its status transition history. Use these endpoints to start, stop, force-stop, restart, pause, or resume a computer, or to retrieve paginated status logs.
In the Hub, open Computers, select a computer and use its action menu to Start, Stop, Restart or Resume it.
Get computer status logs
Section titled “Get computer status logs”GET /api/v1/computers/{id}/status-logs
Section titled “GET /api/v1/computers/{id}/status-logs”Returns a paginated list of status transition logs for a specific computer. Each entry records the previous and new status, the actor that triggered the transition, the duration of the status change in milliseconds, and any metadata captured at the moment of the transition. For a lifecycle operation, duration_ms records how long the operation ran. The duration is null when it was not measured.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Computer ID |
page | query | number | No | Page number. Default: 1 |
limit | query | number | No | Items per page. Default: 10 |
sort_by | query | string | No | Field to sort by. Default: "transition_time". One of: "transition_time", "created_at", "to_status", "from_status" |
sort_order | query | string | No | Sort direction. Default: "desc". One of: "asc", "desc" |
This endpoint takes no request body.
Example request
Section titled “Example request”curl -X GET 'https://api.hoody.com/api/v1/computers/{id}/status-logs?page=1&limit=10&sort_by=transition_time&sort_order=desc' \ -H 'Authorization: Bearer <token>'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const id = '67e89abc123def456789abcd';
await client.api.computers.listStatusHistory(id, { page: 1, limit: 10, sort_by: 'transition_time', sort_order: 'desc'});Response
Section titled “Response”The status logs were retrieved successfully.
Media type: application/json
{ "statusCode": 200, "message": "Status logs retrieved successfully", "data": { "logs": [ { "id": "507f1f77bcf86cd799439077", "computer_id": "507f1f77bcf86cd799439011", "from_status": "stopped", "to_status": "running", "transition_time": "2025-01-15T10:30:00.000Z", "duration_ms": 3500, "triggered_by": "manual_operation", "metadata": { "kind": "computer_operation", "operation": "start", "actor_user_id": "507f1f77bcf86cd799439022" } }, { "id": "507f1f77bcf86cd799439078", "computer_id": "507f1f77bcf86cd799439011", "from_status": "running", "to_status": "stopped", "transition_time": "2025-01-15T09:15:00.000Z", "duration_ms": 90000, "triggered_by": "manual_operation", "metadata": { "kind": "computer_operation", "operation": "stop", "actor_user_id": "507f1f77bcf86cd799439022" } } ], "pagination": { "total": 15, "page": 1, "limit": 10, "totalPages": 2 } }}Authentication could not be completed.
Media type: application/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 <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 token 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 has not been 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, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also implicitly verifies the email. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
The account does not have permission to retrieve the status logs.
Media type: application/json
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
The requested computer was not found.
Media type: application/json
{ "statusCode": 404, "error": "Not Found", "message": "Computer with ID 507f1f77bcf86cd799439011 not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NOT_FOUND | Computer not found | No computer with this ID exists. | Verify the computer ID is correct. |
The request does not match the operation schema.
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must match pattern \"^[0-9a-f]{24}$\""}The request limit for this operation was exceeded.
Media type: application/json
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. The body’s error is Too Many Requests. | Wait the number of seconds in the Retry-After header, then try again. |
Manage computer
Section titled “Manage computer”POST /api/v1/computers/{id}/{operation}
Section titled “POST /api/v1/computers/{id}/{operation}”Performs a lifecycle operation on a computer. The operation path segment selects the action: start, stop, force-stop, restart, pause, or resume. Each successful operation returns the computer’s new status and a message describing the outcome.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Unique identifier of the computer to manage |
operation | path | string | Yes | Lifecycle operation to perform. One of: start, stop, force-stop, restart, pause, resume |
Request body
Section titled “Request body”The body is optional. When present, it may carry the following field:
| Name | Type | Required | Description |
|---|---|---|---|
timeout | integer | No | For stop and restart, the time in seconds given for a clean shutdown. After this deadline, the computer is stopped forcibly and, for restart, started again, so the operation may run up to 420 seconds longer. For other operations, an upper bound in seconds on how long the operation may run before it is cut off. The minimum is 1 and the maximum is 600. If omitted, stop and restart use a 60-second clean-shutdown deadline, while other operations have no cut-off. |
{ "timeout": 120}Example request
Section titled “Example request”curl -X POST 'https://api.hoody.com/api/v1/computers/{id}/start' \ -H 'Authorization: Bearer <token>' \ -H 'Content-Type: application/json' \ -d '{"timeout": 120}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });
const id = '67e89abc123def456789abcd';
await client.api.computers.start(id, { timeout: 120 });The SDK exposes this operation through five named methods:
client.api.computers.start(id, data)setsoperationtostart.client.api.computers.restart(id, data)setsoperationtorestart.client.api.computers.pause(id, data)setsoperationtopause.client.api.computers.resume(id, data)setsoperationtoresume.client.api.computers.stop(id, data, options?)setsoperationtoforce-stopwhenoptions.forceis truthy, otherwise setsoperationtostop.
The caller does not pass the operation path value directly because each SDK method sets it.
Response
Section titled “Response”The computer operation completed successfully.
Media type: application/json
{ "statusCode": 200, "message": "Computer started.", "data": { "error": false, "operation": "start", "computer_id": "507f1f77bcf86cd799439011", "project_id": "507f1f77bcf86cd799439033", "message": "Computer started.", "status": "running", "operation_id": "9f86d081884c7d659a2feaa0c55ad015" }}The computer is not in a state that allows the operation.
Media type: application/json
{ "statusCode": 400, "error": "Bad Request", "message": "Computer is already running", "data": { "error": true, "operation": "start", "computer_id": "507f1f77bcf86cd799439011", "project_id": "507f1f77bcf86cd799439033", "message": "Computer is already running", "status": "running" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
OPERATION_STATE_CONFLICT | Computer not in a manageable state | The computer is not running, stopped, or paused, or a pause was requested for a stopped computer. | Check the computer’s current status. It must be running, stopped, or paused, and a stopped computer cannot be paused. |
Authentication could not be completed.
Media type: application/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 <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 provided authentication token has expired | Obtain a new token by logging in again or refreshing your session |
AUTH_TOKEN_LINEAGE_REVOKED | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token 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 | Returned by the login endpoint when the password is correct but the account’s email address has not been verified yet. It is only returned after the password has been checked. The response carries data.email so the client can offer a resend verification email action without asking again. | Complete email verification by clicking the link sent to your inbox, call POST /api/v1/auth/resend-verification to receive a new link, or complete a password reset, which also implicitly verifies the email. |
INVALID_OTP_CODE | Invalid OTP code | The provided 2FA code is incorrect or has expired | Generate a new code from your authenticator app and try again |
The account is not permitted to perform the operation.
Media type: application/json
{ "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INSUFFICIENT_PERMISSIONS | Insufficient permissions | You do not have the required permissions to perform this action | Ask the resource owner to grant you access |
ACCOUNT_BANNED | Account banned | Your account has been banned and cannot access this resource | Contact support for information about your account status |
ACCESS_SUSPENDED | Computer access is suspended | The computer is under an access suspension and must stay stopped. start, resume, and restart are refused. | Contact support. The computer can be started once the suspension is lifted. |
The requested computer was not found.
Media type: application/json
{ "statusCode": 404, "error": "Not Found", "message": "Computer not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_NOT_FOUND | Computer not found | The requested computer does not exist or you do not have permission to access it. | Verify the computer ID is correct and that you have access to the project it belongs to. |
The operation conflicts with the computer’s current lifecycle state.
Media type: application/json
{ "statusCode": 409, "error": "COMPUTER_OPERATION_IN_PROGRESS", "message": "Cannot perform start operation. Computer is currently being operated on."}| 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, whether it is on hold, being delivered, or being deleted, or a change is in progress, so the operation is refused. data holds the operation result, including operation, computer_id, and status. Nothing was changed. | Retry once the subserver is active again, such as after renewing a held subscription or waiting for the change to finish. |
The request does not match the operation schema, or its JSON body cannot be parsed.
Media type: application/json
{ "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must match pattern \"^[0-9a-f]{24}$\""}The request limit for this operation was exceeded.
Media type: application/json
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RATE_LIMIT_EXCEEDED | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked, so try again in a few seconds. |
An unexpected server error prevented the operation from completing.
Media type: application/json
{ "statusCode": 500, "error": "Internal Server Error", "message": "An unexpected error occurred"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
INTERNAL_SERVER_ERROR | Internal server error | An unexpected error occurred on the server | Try again later, or contact support if the problem persists |
The computer’s server could not complete the operation.
Media type: application/json
{ "statusCode": 502, "error": "COMPUTER_HOST_COMMAND_FAILED", "message": "Computer operation failed: server is temporarily unreachable. Please try again shortly."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_HOST_COMMAND_FAILED | The computer server could not complete the operation | The computer’s server was unreachable, or ran the operation and reported a failure. | Check the computer status, then retry. If it keeps failing, contact support. |
The computer’s server did not answer before the deadline.
Media type: application/json
{ "statusCode": 504, "error": "COMPUTER_HOST_TIMEOUT", "message": "Computer operation timed out waiting for the server. Its outcome is unknown; check the computer status before retrying."}| Error Code | Title | Description | Resolution |
|---|---|---|---|
COMPUTER_HOST_TIMEOUT | The computer server did not answer in time | The operation was sent but the server did not answer before the deadline. It may still have completed. | Check the computer status before retrying. |