# Computer Operations & Lifecycle **Page:** api/computer-operations [Download Raw Markdown](./api/computer-operations.md) --- # 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. Requests use a sign-in token (JWT), an auth token, or HTTP Basic credentials (username and password, or an auth token) in the `Authorization` header. Operations act on a single computer identified by its 24-character lowercase hexadecimal ID. In the Hub, open Computers, select a computer and use its action menu to Start, Stop, Restart or Resume it. ## Get computer status logs ### `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 | 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 ```bash 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 ' ``` ```typescript 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 The status logs were retrieved successfully. Media type: application/json ```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 ```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 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 ```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 ```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 ```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 ```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 ### `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. Some operations require the computer to be in a specific current state. For example, a computer must be stopped before it can be started. Calling an operation against an incompatible state returns a 400 response. ### 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 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. | ```json { "timeout": 120 } ``` ### Example request ```bash curl -X POST 'https://api.hoody.com/api/v1/computers/{id}/start' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"timeout": 120}' ``` ```typescript 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)` sets `operation` to `start`. - `client.api.computers.restart(id, data)` sets `operation` to `restart`. - `client.api.computers.pause(id, data)` sets `operation` to `pause`. - `client.api.computers.resume(id, data)` sets `operation` to `resume`. - `client.api.computers.stop(id, data, options?)` sets `operation` to `force-stop` when `options.force` is truthy, otherwise sets `operation` to `stop`. The caller does not pass the `operation` path value directly because each SDK method sets it. ### Response The computer operation completed successfully. Media type: application/json ```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 ```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 ```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 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 ```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 ```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 ```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 ```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 ```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 ```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 ```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 ```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. |