# Databases (Admin)

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

*List databases for an account*

Returns every database owned by the given account.

**Path parameters:**

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

**Responses:**

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

**Response example (200):**

```json
{
  "data": [
    {
      "charset": "...",
      "collation": "...",
      "name": "...",
      "remote_hosts": "...",
      "size_mb": "...",
      "users": "..."
    }
  ],
  "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}/databases
```

---

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

*Create database*

Create a new MariaDB database for the account, auto-prefixed with `{username}_`. Enforces the plan's `max_databases` cap.

**Path parameters:**

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

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `charset` | string | no | default `utf8mb4` |
| `collation` | string | no | default `utf8mb4_unicode_ci` |
| `name` | string | yes | minLength=1; maxLength=47; pattern=`^[a-z][a-z0-9_]{0,46}$` |

**Request body example:**

```json
{
  "charset": "utf8mb4",
  "collation": "utf8mb4_unicode_ci",
  "name": "string"
}
```

**Responses:**

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

**Response example (200):**

```json
{
  "data": {
    "charset": "utf8mb4",
    "collation": "utf8mb4_unicode_ci",
    "name": "string",
    "remote_hosts": [
      "..."
    ],
    "size_mb": 0.0,
    "users": [
      "..."
    ]
  },
  "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}/databases
```

---

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

*Delete database*

Drop the database and remove its user/grant entries.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `db_name` | 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}/databases/{db_name}
```

---

<a id="get-api-v1-accounts-username-databases-db-name-phpmyadmin-url"></a>
#### `GET /api/v1/accounts/{username}/databases/{db_name}/phpmyadmin-url`

*Mint phpMyAdmin SSO URL*

Returns a short-lived SSO login URL for the panel's embedded phpMyAdmin. Returns a 200 with `error_code=PMA_NOT_INSTALLED` when phpMyAdmin is not present — handle both shapes client-side.

**Path parameters:**

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

**Responses:**

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

**Response example (200):**

```json
{}
```

**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}/databases/{db_name}/phpmyadmin-url
```

---

<a id="get-api-v1-accounts-username-databases-db-name-remote-hosts"></a>
#### `GET /api/v1/accounts/{username}/databases/{db_name}/remote-hosts`

*List remote hosts*

Returns the IPs / patterns currently allowed to connect to this database.

**Path parameters:**

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

**Responses:**

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

**Response example (200):**

```json
{
  "data": [
    {
      "host": "...",
      "note": "...",
      "users": "..."
    }
  ],
  "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}/databases/{db_name}/remote-hosts
```

---

<a id="post-api-v1-accounts-username-databases-db-name-remote-hosts"></a>
#### `POST /api/v1/accounts/{username}/databases/{db_name}/remote-hosts`

*Add remote host*

Whitelist a host/IP pattern for remote database access.

**Path parameters:**

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

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `host` | string | yes | — |
| `note` | string | no | default `` |

**Request body example:**

```json
{
  "host": "string",
  "note": ""
}
```

**Responses:**

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

**Response example (200):**

```json
{
  "data": {
    "host": "string",
    "note": "",
    "users": [
      "..."
    ]
  },
  "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}/databases/{db_name}/remote-hosts
```

---

<a id="delete-api-v1-accounts-username-databases-db-name-remote-hosts-host"></a>
#### `DELETE /api/v1/accounts/{username}/databases/{db_name}/remote-hosts/{host}`

*Remove remote host*

Revoke remote access for the given host pattern.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `db_name` | string | yes | — |
| `host` | 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}/databases/{db_name}/remote-hosts/{host}
```

---

<a id="post-api-v1-accounts-username-databases-db-name-users"></a>
#### `POST /api/v1/accounts/{username}/databases/{db_name}/users`

*Create database user*

Create a new MariaDB user and grant it access to this database.

**Path parameters:**

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

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `host` | string | no | default `localhost` |
| `password` | string | yes | — |
| `privileges` | array<string> | no | — |
| `username` | string | yes | minLength=1; maxLength=15; pattern=`^[a-z][a-z0-9_]{0,14}$` |

**Request body example:**

```json
{
  "host": "localhost",
  "password": "REPLACE_ME",
  "privileges": [
    "string"
  ],
  "username": "alice"
}
```

**Responses:**

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

**Response example (200):**

```json
{
  "data": {
    "host": "string",
    "privileges": [
      "..."
    ],
    "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}/databases/{db_name}/users
```

---

<a id="delete-api-v1-accounts-username-databases-db-name-users-db-user"></a>
#### `DELETE /api/v1/accounts/{username}/databases/{db_name}/users/{db_user}`

*Delete database user*

Revoke + drop the MariaDB user.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `db_name` | string | yes | — |
| `db_user` | 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}/databases/{db_name}/users/{db_user}
```

---

<a id="put-api-v1-accounts-username-databases-db-name-users-db-user"></a>
#### `PUT /api/v1/accounts/{username}/databases/{db_name}/users/{db_user}`

*Update database user (password reset)*

Currently only rotates the MariaDB password for an existing user.

**Path parameters:**

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

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `password` | string | no | — |

**Request body example:**

```json
{
  "password": "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 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}/databases/{db_name}/users/{db_user}
```

---

<a id="delete-api-v1-accounts-username-databases-db-name-users-db-user-grants"></a>
#### `DELETE /api/v1/accounts/{username}/databases/{db_name}/users/{db_user}/grants`

*Revoke a user's access to this database*

Removes the user's privileges on this database only. The user keeps its grants on other databases and is dropped when none remain.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `username` | string | yes | — |
| `db_name` | string | yes | — |
| `db_user` | 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}/databases/{db_name}/users/{db_user}/grants
```

---

<a id="post-api-v1-accounts-username-databases-db-name-users-db-user-grants"></a>
#### `POST /api/v1/accounts/{username}/databases/{db_name}/users/{db_user}/grants`

*Grant existing user access to another database*

Used by the panel's 'Assign User' flow when the user already exists on a different DB — issues a GRANT only (no CREATE USER).

**Path parameters:**

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

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `privileges` | array<string> | no | — |

**Request body example:**

```json
{
  "privileges": [
    "string"
  ]
}
```

**Responses:**

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

**Response example (200):**

```json
{
  "data": {
    "host": "string",
    "privileges": [
      "..."
    ],
    "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}/databases/{db_name}/users/{db_user}/grants
```

---