# Computer Network **Page:** api/computer-network [Download Raw Markdown](./api/computer-network.md) --- # Computer network Use these endpoints to inspect, configure, start, stop, and remove a computer's network proxy or blocking configuration. These endpoints use the Hoody control plane and require a Hoody account token. ## Read and update network configuration ### `GET /api/v1/computers/{id}/network` Returns the current network configuration and status for a computer. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | Unique identifier of the computer to retrieve network configuration for | This endpoint does not accept a request body. ### Request ```bash curl --request GET \ --url 'https://api.hoody.com/api/v1/computers/{id}/network' \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header "Accept: application/json" ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const id = '{id}'; await client.api.network.get(id); ``` ### Response **`200` response fields** | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `message` | string | Result message. | | `data` | object | Network configuration and status. When `configured` is false, only `computer_id` and `configured` are returned. | | `data.computer_id` | string | Unique identifier of the computer. | | `data.configured` | boolean | Whether network configuration exists. | | `data.type` | string | Network configuration type. Allowed values are `socks5`, `http`, `https`, and `block`. | | `data.proxy` | string | Proxy server URL. | | `data.credentials_configured` | boolean | Whether proxy credentials are stored. This field is present for owners, administrators, and collaborators with edit access. | | `data.country` | string | Descriptive country label stored with the configuration. It does not select or change the proxy location. | | `data.city` | string | Descriptive city label stored with the configuration. It does not select or change the proxy location. | | `data.region` | string | Descriptive region label stored with the configuration. It does not select or change the proxy location. | | `data.comment` | string | Comment describing the network configuration. | | `data.dns_servers` | array | Custom DNS server addresses. | | `data.status` | string | Network status. Allowed values are `configured`, `running`, `stopped`, and `error`. | | `data.configured_at` | string | Date and time when the configuration was created. | | `data.last_status_check` | string | Date and time of the latest status check. | | `data.remote_status` | object or null | Live network status on the computer. This value is null when the status could not be read. | | `data.remote_status.is_running` | boolean | Whether the remote network service is running. | | `data.remote_status.last_check` | string | Date and time of the latest remote status check. | **Error response fields for `400`, `401`, `403`, `404`, `429`, and `500`** | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `error` | string | Error type. | | `message` | string | Error message. | **`422` response fields** | Field | Type | Description | |---|---|---| | `statusCode` | number | Required. HTTP status code. | | `error` | string | Required. Error type. | | `message` | string | Required. Error message. | | `data` | any JSON value | The failing checks, when there are any. | Media type: application/json The current network configuration and status were retrieved. ```json { "statusCode": 200, "message": "Network configuration retrieved successfully", "data": { "computer_id": "507f1f77bcf86cd799439012", "configured": true, "type": "socks5", "proxy": "socks5://proxy.example.com:1080", "credentials_configured": true, "country": "US", "city": "New York", "region": "North America", "comment": "Production proxy configuration", "dns_servers": [ "1.1.1.1", "8.8.8.8" ], "status": "running", "configured_at": "2025-01-15T10:00:00.000Z", "last_status_check": "2025-01-15T20:00:00.000Z", "remote_status": { "is_running": true, "last_check": "2025-01-15T20:00:00.000Z" } } } ``` Media type: application/json The computer has no server assigned. ```json { "statusCode": 400, "error": "Bad Request", "message": "Computer does not have a server assigned" } ``` Media type: application/json Authentication is missing or invalid. ```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 one no longer authenticates | Create a new auth token from a valid one, or sign in again | | `INVALID_CREDENTIALS` | Invalid credentials | The provided username/email or password is incorrect | Verify your credentials and try again, or use the password reset feature | | `EMAIL_NOT_VERIFIED` | Email not verified | Returned by the login endpoint when the password is correct but the account's email address has not been verified yet. It is only returned after the password has been checked. The response carries `data.email` so the client can offer a 'resend verification email' action without asking again. | Complete email verification by clicking the link sent to your inbox, or call `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 | Media type: application/json The account is not permitted to access this computer. ```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 '507f1f77bcf86cd799439012' not found." } ``` Media type: application/json The request does not match the operation schema. The `id` path parameter must match the pattern `^[0-9a-f]{24}$`. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must match pattern \"^[0-9a-f]{24}$\"" } ``` Media type: application/json The operation's request limit was exhausted. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. | Media type: application/json The server could not retrieve the network configuration. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "An error occurred while getting the network configuration" } ``` ### `PUT /api/v1/computers/{id}/network` Configures or updates the network proxy or blocking settings for a computer. Normally, the computer must be running or paused to update its network configuration. Configuration may also be allowed when the computer cannot reach a startable state. `PATCH` is also accepted for this endpoint with identical behavior. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | Unique identifier of the computer to configure network for | ### Request body The request body is required. | Name | Type | Required | Description | |---|---|---|---| | `type` | string | Yes | Network configuration type. Allowed values are `socks5`, `http`, `https`, and `block`. | | `proxy` | string | No | Proxy server URL. Required for non-`block` types and omitted for `block`. For example, `socks5://proxy.example.com:1080`. | | `country` | string | No | Optional descriptive label, at most 100 characters. It is stored and returned as given and does not select or change the proxy location. | | `city` | string | No | Optional descriptive label, at most 100 characters. It is stored and returned as given and does not select or change the proxy location. | | `region` | string | No | Optional descriptive label, at most 100 characters. It is stored and returned as given and does not select or change the proxy location. | | `comment` | string | No | Comment describing the network configuration. Maximum length: 1000 characters. | | `dns_servers` | array | No | DNS server addresses. Maximum: 4. Custom DNS servers are not applied. Any submitted array of at most four entries is accepted and stored as `["1.1.1.1", "8.8.8.8"]`. | `proxy` is required when `type` is not `block`. A non-empty `proxy` is rejected when `type` is `block`. Credentials can be embedded as URL userinfo, such as `socks5://host:port`, to set or replace them. Omitting userinfo on an unchanged endpoint preserves the stored credentials as a write-only secret. The response never echoes userinfo back, so use `credentials_configured` to check whether credentials are configured. ```json { "type": "socks5", "proxy": "socks5://proxy.example.com:1080", "country": "US", "city": "New York", "region": "North America", "comment": "Production proxy for US traffic", "dns_servers": [ "1.1.1.1", "8.8.8.8" ] } ``` ### Request ```bash curl --request PUT \ --url 'https://api.hoody.com/api/v1/computers/{id}/network' \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header "Content-Type: application/json" \ --header "Accept: application/json" \ --data '{ "type": "socks5", "proxy": "socks5://proxy.example.com:1080", "country": "US", "city": "New York", "region": "North America", "comment": "Production proxy for US traffic", "dns_servers": [ "1.1.1.1", "8.8.8.8" ] }' ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const id = '{id}'; const data = { type: 'socks5' as const, proxy: 'socks5://proxy.example.com:1080', country: 'US', city: 'New York', region: 'North America', comment: 'Production proxy for US traffic', dns_servers: ['1.1.1.1', '8.8.8.8'] }; await client.api.network.update(id, data); ``` ### Response **`200` response fields** | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `message` | string | Result message. | | `data` | object | Updated network configuration. | | `data.computer_id` | string | Unique identifier of the computer. | | `data.type` | string | Network configuration type. Allowed values are `socks5`, `http`, `https`, and `block`. | | `data.proxy` | string | Proxy server URL. | | `data.credentials_configured` | boolean | Whether proxy credentials are stored. | | `data.country` | string | Descriptive country label stored with the configuration. It does not select or change the proxy location. | | `data.city` | string | Descriptive city label stored with the configuration. It does not select or change the proxy location. | | `data.region` | string | Descriptive region label stored with the configuration. It does not select or change the proxy location. | | `data.comment` | string | Comment describing the network configuration. | | `data.dns_servers` | array | Custom DNS server addresses. | | `data.status` | string | Network status. Allowed values are `configured`, `running`, `stopped`, and `error`. | | `data.configured_at` | string | Date and time when the configuration was created. | **Error response fields for `400`, `401`, `403`, `404`, `429`, and `500`** | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `error` | string | Error type. | | `message` | string | Error message. | **`409` and `422` response fields** | Field | Type | Description | |---|---|---| | `statusCode` | number | Required. HTTP status code. | | `error` | string | Required. Error type. | | `message` | string | Required. Error message. | | `data` | any JSON value | Additional error details or failing checks, when present. | Media type: application/json The network configuration was updated. ```json { "statusCode": 200, "message": "Network configuration updated successfully", "data": { "computer_id": "507f1f77bcf86cd799439012", "type": "socks5", "proxy": "socks5://proxy.example.com:1080", "credentials_configured": true, "country": "US", "city": "New York", "region": "North America", "comment": "Production proxy for US traffic", "dns_servers": [ "1.1.1.1", "8.8.8.8" ], "status": "configured", "configured_at": "2025-01-15T21:00:00.000Z" } } ``` Media type: application/json The request cannot be applied. This can occur when a non-`block` type has no proxy URL, a `block` type has a non-empty proxy URL, more than four DNS servers are supplied, the computer is neither running nor paused (unless it cannot reach a startable state), or the computer has no server assigned. The response is also retryable while another network change is running. ```json { "statusCode": 400, "error": "Bad Request", "message": "Non-block type must have a proxy URL" } ``` Media type: application/json Authentication is missing or invalid. ```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 one no longer authenticates | Create a new auth token from a valid one, or sign in again | | `INVALID_CREDENTIALS` | Invalid credentials | The provided username/email or password is incorrect | Verify your credentials and try again, or use the password reset feature | | `EMAIL_NOT_VERIFIED` | Email not verified | Returned by the login endpoint when the password is correct but the account's email address has not been verified yet. It is only returned after the password has been checked. The response carries `data.email` so the client can offer a 'resend verification email' action without asking again. | Complete email verification by clicking the link sent to your inbox, or call `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 | Media type: application/json The account is not permitted to configure this computer. ```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 network 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 '507f1f77bcf86cd799439012' not found." } ``` Media type: application/json The network operation conflicts with the current computer or network state. ```json { "statusCode": 409, "error": "NETWORK_OPERATION_SUPERSEDED", "message": "This network operation was superseded by a newer request. Please retry." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NETWORK_OPERATION_SUPERSEDED` | Network change superseded | A newer network request for this computer replaced this one before it ran. | Read the network state and retry if it is still needed. | | `NETWORK_RESOURCE_TORN_DOWN` | Network configuration was removed | The computer's network configuration was removed, so it cannot be started or stopped. | Configure the computer's network again. | | `NETWORK_IDENTITY_CONFLICT` | Network configuration tied to another server | The computer's network configuration is tied to a different server and cannot be moved. Retrying does not help. | Contact support. | | `NETWORK_REQUEST_MISMATCH` | Network request does not match | The request does not match the earlier request it would repeat, such as another computer or other parameters. Retrying the same request does not help. | Send a new request. | | `NETWORK_OPERATION_CONFLICT` | Network change conflict | Another network change for this computer got in the way of this one. Nothing was changed. | Retry. | | `NETWORK_REMOVAL_PENDING` | Network removal not finished | A removal of the computer's network configuration has not finished yet. | Retry once the removal has finished. | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, such as on hold, being delivered, or 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, such as by renewing a held subscription or waiting for the change to finish. | | `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 does not allow network changes | The computer is being created or deleted, or was deleted, so its network cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. | Media type: application/json The request does not match the operation schema, or its JSON body cannot be parsed. The `id` path parameter must match the pattern `^[0-9a-f]{24}$`. The request body must also include `type` with one of the values `socks5`, `http`, `https`, or `block`. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must match pattern \"^[0-9a-f]{24}$\"" } ``` Media type: application/json The operation's request limit was exhausted. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. | Media type: application/json The server could not update the network configuration. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "An error occurred while updating the network configuration" } ``` ## Control and remove network configuration ### `POST /api/v1/computers/{id}/network/start` Starts the network proxy or blocking service for a computer. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | Unique identifier of the computer to start network for | This endpoint does not accept a request body. ### Request ```bash curl --request POST \ --url 'https://api.hoody.com/api/v1/computers/{id}/network/start' \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header "Accept: application/json" ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const id = '{id}'; await client.api.network.start(id); ``` ### Response **`200` response fields** | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `message` | string | Result message. | | `data` | object | Network service status. | | `data.computer_id` | string | Unique identifier of the computer. | | `data.status` | string | Network status. Allowed values are `configured`, `running`, `stopped`, and `error`. | | `data.is_running` | boolean | Whether the network service is running. | | `data.last_check` | string | Date and time of the latest status check. | **Error response fields for `400`, `401`, `403`, `404`, `429`, and `500`** | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `error` | string | Error type. | | `message` | string | Error message. | **`409` and `422` response fields** | Field | Type | Description | |---|---|---| | `statusCode` | number | Required. HTTP status code. | | `error` | string | Required. Error type. | | `message` | string | Required. Error message. | | `data` | any JSON value | Additional error details or failing checks, when present. | Media type: application/json The network was started. ```json { "statusCode": 200, "message": "Network started successfully", "data": { "computer_id": "507f1f77bcf86cd799439012", "status": "running", "is_running": true, "last_check": "2025-01-15T21:05:00.000Z" } } ``` Media type: application/json The network is not configured, the computer is neither running nor paused, or the computer has no server assigned. The response is also retryable while another network change is running. ```json { "statusCode": 400, "error": "Bad Request", "message": "Network must be configured before it can be started" } ``` Media type: application/json Authentication is missing or invalid. ```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 one no longer authenticates | Create a new auth token from a valid one, or sign in again | | `INVALID_CREDENTIALS` | Invalid credentials | The provided username/email or password is incorrect | Verify your credentials and try again, or use the password reset feature | | `EMAIL_NOT_VERIFIED` | Email not verified | Returned by the login endpoint when the password is correct but the account's email address has not been verified yet. It is only returned after the password has been checked. The response carries `data.email` so the client can offer a 'resend verification email' action without asking again. | Complete email verification by clicking the link sent to your inbox, or call `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 | Media type: application/json The account is not permitted to start the network service for this computer. ```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 network 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 '507f1f77bcf86cd799439012' not found." } ``` Media type: application/json The network operation conflicts with the current computer or network state. ```json { "statusCode": 409, "error": "NETWORK_OPERATION_SUPERSEDED", "message": "This network operation was superseded by a newer request. Please retry." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NETWORK_OPERATION_SUPERSEDED` | Network change superseded | A newer network request for this computer replaced this one before it ran. | Read the network state and retry if it is still needed. | | `NETWORK_RESOURCE_TORN_DOWN` | Network configuration was removed | The computer's network configuration was removed, so it cannot be started or stopped. | Configure the computer's network again. | | `NETWORK_IDENTITY_CONFLICT` | Network configuration tied to another server | The computer's network configuration is tied to a different server and cannot be moved. Retrying does not help. | Contact support. | | `NETWORK_REQUEST_MISMATCH` | Network request does not match | The request does not match the earlier request it would repeat, such as another computer or other parameters. Retrying the same request does not help. | Send a new request. | | `NETWORK_OPERATION_CONFLICT` | Network change conflict | Another network change for this computer got in the way of this one. Nothing was changed. | Retry. | | `NETWORK_REMOVAL_PENDING` | Network removal not finished | A removal of the computer's network configuration has not finished yet. | Retry once the removal has finished. | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, such as on hold, being delivered, or 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, such as by renewing a held subscription or waiting for the change to finish. | | `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 does not allow network changes | The computer is being created or deleted, or was deleted, so its network cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. | Media type: application/json The request does not match the operation schema. The `id` path parameter must match the pattern `^[0-9a-f]{24}$`. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must match pattern \"^[0-9a-f]{24}$\"" } ``` Media type: application/json The operation's request limit was exhausted. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. | Media type: application/json The server could not start the network. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "An error occurred while starting the network" } ``` ### `POST /api/v1/computers/{id}/network/stop` Stops the network proxy or blocking service for a computer. The configuration is preserved and can be started again with the start endpoint. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | Unique identifier of the computer to stop network for | This endpoint does not accept a request body. ### Request ```bash curl --request POST \ --url 'https://api.hoody.com/api/v1/computers/{id}/network/stop' \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header "Accept: application/json" ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const id = '{id}'; await client.api.network.stop(id); ``` ### Response **`200` response fields** | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `message` | string | Result message. | | `data` | object | Network service status. | | `data.computer_id` | string | Unique identifier of the computer. | | `data.status` | string | Network status. Allowed values are `configured`, `running`, `stopped`, and `error`. | | `data.is_running` | boolean | Whether the network service is running. | | `data.last_check` | string | Date and time of the latest status check. | **Error response fields for `400`, `401`, `403`, `404`, `429`, and `500`** | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `error` | string | Error type. | | `message` | string | Error message. | **`409` and `422` response fields** | Field | Type | Description | |---|---|---| | `statusCode` | number | Required. HTTP status code. | | `error` | string | Required. Error type. | | `message` | string | Required. Error message. | | `data` | any JSON value | Additional error details or failing checks, when present. | Media type: application/json The network was stopped. ```json { "statusCode": 200, "message": "Network stopped successfully", "data": { "computer_id": "507f1f77bcf86cd799439012", "status": "stopped", "is_running": false, "last_check": "2025-01-15T21:10:00.000Z" } } ``` Media type: application/json The computer is neither running nor paused, or it has no server assigned. The response is also retryable while another network change is running. ```json { "statusCode": 400, "error": "Bad Request", "message": "Computer must be in \"running\" or \"paused\" state to stop its network. Current status: \"stopped\"" } ``` Media type: application/json Authentication is missing or invalid. ```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 one no longer authenticates | Create a new auth token from a valid one, or sign in again | | `INVALID_CREDENTIALS` | Invalid credentials | The provided username/email or password is incorrect | Verify your credentials and try again, or use the password reset feature | | `EMAIL_NOT_VERIFIED` | Email not verified | Returned by the login endpoint when the password is correct but the account's email address has not been verified yet. It is only returned after the password has been checked. The response carries `data.email` so the client can offer a 'resend verification email' action without asking again. | Complete email verification by clicking the link sent to your inbox, or call `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 | Media type: application/json The account is not permitted to stop the network service for this computer. ```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 network 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 '507f1f77bcf86cd799439012' not found." } ``` Media type: application/json The network operation conflicts with the current computer or network state. ```json { "statusCode": 409, "error": "NETWORK_OPERATION_SUPERSEDED", "message": "This network operation was superseded by a newer request. Please retry." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NETWORK_OPERATION_SUPERSEDED` | Network change superseded | A newer network request for this computer replaced this one before it ran. | Read the network state and retry if it is still needed. | | `NETWORK_RESOURCE_TORN_DOWN` | Network configuration was removed | The computer's network configuration was removed, so it cannot be started or stopped. | Configure the computer's network again. | | `NETWORK_IDENTITY_CONFLICT` | Network configuration tied to another server | The computer's network configuration is tied to a different server and cannot be moved. Retrying does not help. | Contact support. | | `NETWORK_REQUEST_MISMATCH` | Network request does not match | The request does not match the earlier request it would repeat, such as another computer or other parameters. Retrying the same request does not help. | Send a new request. | | `NETWORK_OPERATION_CONFLICT` | Network change conflict | Another network change for this computer got in the way of this one. Nothing was changed. | Retry. | | `NETWORK_REMOVAL_PENDING` | Network removal not finished | A removal of the computer's network configuration has not finished yet. | Retry once the removal has finished. | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, such as on hold, being delivered, or 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, such as by renewing a held subscription or waiting for the change to finish. | | `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 does not allow network changes | The computer is being created or deleted, or was deleted, so its network cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. | Media type: application/json The request does not match the operation schema. The `id` path parameter must match the pattern `^[0-9a-f]{24}$`. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must match pattern \"^[0-9a-f]{24}$\"" } ``` Media type: application/json The operation's request limit was exhausted. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. | Media type: application/json The server could not stop the network. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "An error occurred while stopping the network" } ``` ### `DELETE /api/v1/computers/{id}/network` Removes the entire network proxy or blocking configuration for a computer. The computer falls back to direct network access once the configuration is cleared. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | Unique identifier of the computer to remove network configuration from | This endpoint does not accept a request body. ### Request ```bash curl --request DELETE \ --url 'https://api.hoody.com/api/v1/computers/{id}/network' \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header "Accept: application/json" ``` ```ts import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const id = '{id}'; await client.api.network.delete(id); ``` ### Response **`200` response fields** | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `message` | string | Result message. | **Error response fields for `400`, `401`, `403`, `404`, `429`, and `500`** | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `error` | string | Error type. | | `message` | string | Error message. | **`409` and `422` response fields** | Field | Type | Description | |---|---|---| | `statusCode` | number | Required. HTTP status code. | | `error` | string | Required. Error type. | | `message` | string | Required. Error message. | | `data` | any JSON value | Additional error details or failing checks, when present. | Media type: application/json The network configuration was removed. ```json { "statusCode": 200, "message": "Network configuration removed successfully" } ``` Media type: application/json The computer has no server assigned. The response is also retryable while another network change is running. ```json { "statusCode": 400, "error": "Bad Request", "message": "Computer does not have a server assigned" } ``` Media type: application/json Authentication is missing or invalid. ```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 one no longer authenticates | Create a new auth token from a valid one, or sign in again | | `INVALID_CREDENTIALS` | Invalid credentials | The provided username/email or password is incorrect | Verify your credentials and try again, or use the password reset feature | | `EMAIL_NOT_VERIFIED` | Email not verified | Returned by the login endpoint when the password is correct but the account's email address has not been verified yet. It is only returned after the password has been checked. The response carries `data.email` so the client can offer a 'resend verification email' action without asking again. | Complete email verification by clicking the link sent to your inbox, or call `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 | Media type: application/json The account is not permitted to remove this computer's network configuration. ```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 network 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, or the computer has no network configuration. ```json { "statusCode": 404, "error": "Not Found", "message": "Network configuration for computer 507f1f77bcf86cd799439012 not found" } ``` Media type: application/json The network operation conflicts with the current computer or network state. ```json { "statusCode": 409, "error": "NETWORK_OPERATION_SUPERSEDED", "message": "This network operation was superseded by a newer request. Please retry." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `NETWORK_OPERATION_SUPERSEDED` | Network change superseded | A newer network request for this computer replaced this one before it ran. | Read the network state and retry if it is still needed. | | `NETWORK_RESOURCE_TORN_DOWN` | Network configuration was removed | The computer's network configuration was removed, so it cannot be started or stopped. | Configure the computer's network again. | | `NETWORK_IDENTITY_CONFLICT` | Network configuration tied to another server | The computer's network configuration is tied to a different server and cannot be moved. Retrying does not help. | Contact support. | | `NETWORK_REQUEST_MISMATCH` | Network request does not match | The request does not match the earlier request it would repeat, such as another computer or other parameters. Retrying the same request does not help. | Send a new request. | | `NETWORK_OPERATION_CONFLICT` | Network change conflict | Another network change for this computer got in the way of this one. Nothing was changed. | Retry. | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, such as on hold, being delivered, or 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, such as by renewing a held subscription or waiting for the change to finish. | | `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 does not allow network changes | The computer is being created or deleted, or was deleted, so its network cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. | Media type: application/json The request does not match the operation schema. The `id` path parameter must match the pattern `^[0-9a-f]{24}$`. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must match pattern \"^[0-9a-f]{24}$\"" } ``` Media type: application/json The operation's request limit was exhausted. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |------------|-------|-------------|------------| | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the Retry-After header, then try again. When there is no Retry-After header, the limit could not be checked: try again in a few seconds. | Media type: application/json The server could not remove the network configuration. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "An error occurred while removing the network configuration" } ```