# Accounts

<a id="get-api-v1-accounts"></a>
#### `GET /api/v1/accounts`

*List hosting accounts*

Paginated list of accounts with optional status / search / reseller-only filtering. Returns the standard `{status, data}` envelope where `data` is `{accounts, total, limit, offset}`.

**Query parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `limit` | integer | no | minimum=1; maximum=1000 |
| `offset` | integer | no | minimum=0 |
| `sort` | string | no | pattern=`^(created_at\|username)$` |
| `order` | string | no | pattern=`^(asc\|desc)$` |
| `status` | string | no | — |
| `search` | string | no | — |
| `is_reseller` | boolean | no | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_PaginatedAccountsData_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "accounts": [
      "..."
    ],
    "limit": 1.0,
    "offset": 0,
    "total": 0
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts
```

---

<a id="post-api-v1-accounts"></a>
#### `POST /api/v1/accounts`

*Create hosting account*

Provision a new account with the requested plan and primary domain. Returns the persisted account record on success.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `auto_ssl` | boolean | no | default `True` |
| `domain` | string | yes | — |
| `email` | string | yes | — |
| `ip_address` | string | no | — |
| `is_reseller` | boolean | no | default `False` |
| `package` | PackageLimits | no | — |
| `password` | string | yes | At least 8 characters and at most 72 bytes when UTF-8 encoded. |
| `php_version` | string | no | — |
| `plan_id` | string | no | — |
| `reseller_acl_plan_id` | string | no | — |
| `reseller_limits` | ResellerLimits | no | — |
| `reseller_owner` | string | no | — |
| `setup_mail_dns` | boolean | no | default `True` |
| `shell_access` | boolean | no | default `False` |
| `username` | string | yes | — |
| `webserver` | string | no | — |

**Request body example:**

```json
{
  "auto_ssl": true,
  "domain": "example.com",
  "email": "user@example.com",
  "ip_address": "string",
  "is_reseller": false,
  "package": {
    "bandwidth_mb": 10240,
    "disk_mb": 1024,
    "email_hourly_limit": 100,
    "max_databases": 1,
    "max_domains": 1,
    "max_email_accounts": 5,
    "max_ftp_accounts": 5,
    "max_node_apps": 0,
    "max_parked_domains": 1,
    "max_python_apps": 0,
    "max_subdomains": 5,
    "node_max_memory_mb": 0,
    "node_workers_limit": 4,
    "python_workers_limit": 4,
    "resource": {
      "cpu_limit": "...",
      "io_read_mbps": "...",
      "io_write_mbps": "...",
      "iops_read": "...",
      "iops_write": "...",
      "memory_mb": "...",
      "nproc": "..."
    }
  },
  "password": "REPLACE_ME",
  "php_version": "string",
  "plan_id": "string",
  "reseller_acl_plan_id": "string",
  "reseller_limits": {
    "max_accounts": 10,
    "max_bandwidth_mb": 102400,
    "max_databases": 10,
    "max_disk_mb": 10240,
    "max_domains": 10,
    "max_email_accounts": 50,
    "max_ftp_accounts": 10,
    "overselling": false
  },
  "reseller_owner": "string",
  "setup_mail_dns": true,
  "shell_access": false,
  "username": "alice",
  "webserver": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_AccountResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "auto_ssl": true,
    "created_at": "...",
    "domain": "example.com",
    "email": "user@example.com",
    "home_dir": "string",
    "ip_address": "...",
    "is_reseller": false,
    "package": "...",
    "php_version": "string",
    "plan_id": "...",
    "post_create_issues": [
      "..."
    ],
    "reseller_acl_plan_id": "...",
    "reseller_limits": "...",
    "reseller_owner": "...",
    "setup_mail_dns": true,
    "shell_access": false,
    "status": "...",
    "sub_account_count": "...",
    "subdomains": [
      "..."
    ],
    "suspend_reason": "...",
    "updated_at": "...",
    "username": "alice",
    "webserver": "..."
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts
```

---

<a id="delete-api-v1-accounts-username"></a>
#### `DELETE /api/v1/accounts/{username}`

*Terminate account*

Permanently delete an account: removes home directory, Linux user, databases, FTP users, virtual hosts and metadata. Not reversible.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}
```

---

<a id="get-api-v1-accounts-username"></a>
#### `GET /api/v1/accounts/{username}`

*Get account by username*

Fetch a single account's full record.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_AccountResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "auto_ssl": true,
    "created_at": "...",
    "domain": "example.com",
    "email": "user@example.com",
    "home_dir": "string",
    "ip_address": "...",
    "is_reseller": false,
    "package": "...",
    "php_version": "string",
    "plan_id": "...",
    "post_create_issues": [
      "..."
    ],
    "reseller_acl_plan_id": "...",
    "reseller_limits": "...",
    "reseller_owner": "...",
    "setup_mail_dns": true,
    "shell_access": false,
    "status": "...",
    "sub_account_count": "...",
    "subdomains": [
      "..."
    ],
    "suspend_reason": "...",
    "updated_at": "...",
    "username": "alice",
    "webserver": "..."
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}
```

---

<a id="put-api-v1-accounts-username"></a>
#### `PUT /api/v1/accounts/{username}`

*Update account*

Partially update an account (only fields present in the body are mutated). May emit `warnings[]` for non-fatal advisories such as partial config rollback notices.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `auto_ssl` | boolean | no | — |
| `domain` | string | no | — |
| `email` | string | no | — |
| `ip_address` | string | no | — |
| `is_reseller` | boolean | no | — |
| `package` | PackageLimits | no | — |
| `php_version` | string | no | — |
| `plan_id` | string | no | — |
| `reseller_acl_plan_id` | string | no | — |
| `reseller_limits` | ResellerLimits | no | — |
| `reseller_owner` | string | no | — |
| `setup_mail_dns` | boolean | no | — |
| `shell_access` | boolean | no | — |
| `webserver` | string | no | — |

**Request body example:**

```json
{
  "auto_ssl": false,
  "domain": "string",
  "email": "string",
  "ip_address": "string",
  "is_reseller": false,
  "package": {
    "bandwidth_mb": 10240,
    "disk_mb": 1024,
    "email_hourly_limit": 100,
    "max_databases": 1,
    "max_domains": 1,
    "max_email_accounts": 5,
    "max_ftp_accounts": 5,
    "max_node_apps": 0,
    "max_parked_domains": 1,
    "max_python_apps": 0,
    "max_subdomains": 5,
    "node_max_memory_mb": 0,
    "node_workers_limit": 4,
    "python_workers_limit": 4,
    "resource": "..."
  },
  "php_version": "string",
  "plan_id": "string",
  "reseller_acl_plan_id": "string",
  "reseller_limits": {
    "max_accounts": 10,
    "max_bandwidth_mb": 102400,
    "max_databases": 10,
    "max_disk_mb": 10240,
    "max_domains": 10,
    "max_email_accounts": 50,
    "max_ftp_accounts": 10,
    "overselling": false
  },
  "reseller_owner": "string",
  "setup_mail_dns": false,
  "shell_access": false,
  "webserver": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_AccountResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "auto_ssl": true,
    "created_at": "...",
    "domain": "example.com",
    "email": "user@example.com",
    "home_dir": "string",
    "ip_address": "...",
    "is_reseller": false,
    "package": "...",
    "php_version": "string",
    "plan_id": "...",
    "post_create_issues": [
      "..."
    ],
    "reseller_acl_plan_id": "...",
    "reseller_limits": "...",
    "reseller_owner": "...",
    "setup_mail_dns": true,
    "shell_access": false,
    "status": "...",
    "sub_account_count": "...",
    "subdomains": [
      "..."
    ],
    "suspend_reason": "...",
    "updated_at": "...",
    "username": "alice",
    "webserver": "..."
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X PUT \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}
```

---

<a id="post-api-v1-accounts-username-change-package"></a>
#### `POST /api/v1/accounts/{username}/change-package`

*Change account plan*

Move an account onto a different plan. Idempotent: changing to the same plan is a no-op (no 422). Returns old vs new package limits + the list of changes applied.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `plan_id` | string | yes | minLength=1 |

**Request body example:**

```json
{
  "plan_id": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_PackageChangeResponse_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "changes_applied": [
      "..."
    ],
    "new_package": "...",
    "new_plan_id": "string",
    "old_package": "...",
    "old_plan_id": "...",
    "username": "alice"
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}/change-package
```

---

<a id="patch-api-v1-accounts-username-password"></a>
#### `PATCH /api/v1/accounts/{username}/password`

*Change account password*

Reset the account's login password. **Session-cookie auth required** — HMAC API keys are rejected with 403 `HMAC_FORBIDDEN_FOR_CREDENTIAL_MUTATION` to keep credential mutation out of machine-to-machine credentials' reach.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `password` | string | yes | At least 8 characters and at most 72 bytes when UTF-8 encoded. |

**Request body example:**

```json
{
  "password": "REPLACE_ME"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X PATCH \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}/password
```

---

<a id="get-api-v1-accounts-username-resources"></a>
#### `GET /api/v1/accounts/{username}/resources`

*Get account resource limits + live usage*

Bundles the account's current cgroup limits, a live usage snapshot, and the `cgroup_supported` flag the panel uses to decide whether to render the usage chart.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_ResourceBundleData_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "cgroup_supported": false,
    "limits": "...",
    "usage": "..."
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/resources
```

---

<a id="put-api-v1-accounts-username-resources"></a>
#### `PUT /api/v1/accounts/{username}/resources`

*Update resource limits*

Patch one or more cgroup limits (CPU %, memory MB, I/O Mbps, IOPS, process count). Only fields present in the body are modified; others retain their current value.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `cpu_limit` | integer | no | — |
| `io_read_mbps` | integer | no | — |
| `io_write_mbps` | integer | no | — |
| `iops_read` | integer | no | — |
| `iops_write` | integer | no | — |
| `memory_mb` | integer | no | — |
| `nproc` | integer | no | — |

**Request body example:**

```json
{
  "cpu_limit": 0,
  "io_read_mbps": 0,
  "io_write_mbps": 0,
  "iops_read": 0,
  "iops_write": 0,
  "memory_mb": 0,
  "nproc": 0
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_ResourceLimits_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "cpu_limit": 100,
    "io_read_mbps": 20,
    "io_write_mbps": 10,
    "iops_read": 1024,
    "iops_write": 512,
    "memory_mb": 512,
    "nproc": 50
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X PUT \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}/resources
```

---

<a id="post-api-v1-accounts-username-suspend"></a>
#### `POST /api/v1/accounts/{username}/suspend`

*Suspend account*

Suspend an account: disables web/mail/ftp/db access and stops outbound mail. Reversible via `/unsuspend`. Optional `reason` is recorded in the audit log.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |

**Request body example:**

```json
{
  "reason": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/accounts/{username}/suspend
```

---

<a id="post-api-v1-accounts-username-unsuspend"></a>
#### `POST /api/v1/accounts/{username}/unsuspend`

*Unsuspend account*

Re-enable a previously suspended account.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/unsuspend
```

---

<a id="get-api-v1-accounts-username-usage"></a>
#### `GET /api/v1/accounts/{username}/usage`

*Get account usage*

Live usage snapshot: disk, bandwidth, domain / database / email / ftp counts, plus a cgroup-derived `resource` block when supported.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_AccountUsage_` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {
    "bandwidth_limit_mb": 0,
    "bandwidth_used_mb": 0.0,
    "database_count": 0,
    "disk_limit_mb": 0,
    "disk_used_mb": 0.0,
    "domain_count": 0,
    "email_count": 0,
    "ftp_count": 0,
    "resource": "..."
  },
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/accounts/{username}/usage
```

---