# Databases endpoints (Admin API)

> 8 FeatherPanel Admin API endpoints from admin/databases.php: methods, paths, auth, permissions, rate limits, parameters and responses.

Source: https://featherpanel.com/docs/api/reference/admin/databases/

Defined in [`backend/app/routes/admin/databases.php`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/databases.php). Authentication used here: **Admin**. Read [Authentication](https://featherpanel.com/docs/api/authentication/) for how to send credentials and [Rate limits and errors](https://featherpanel.com/docs/api/rate-limits-and-errors/) for the response envelope.

Paths, methods, permissions and rate limits come from the route file. Summaries, parameters and response codes come from the OpenAPI annotations on the controllers; endpoints without annotations show only what the route file declares.

## Endpoints

### GET `/api/admin/databases`

- Auth: Admin
- Permission: `admin.databases.view`
- Route name: `admin-databases`
- Controller: [`DatabasesController::index`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/DatabasesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/databases.php#L26)

**Get all databases** Retrieve a paginated list of all database instances with optional filtering by node and search query.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Page number for pagination |
| `limit` | query | integer | no | Number of records per page |
| `search` | query | string | no | Search term to filter databases by name |
| `node_id` | query | integer | no | Filter databases by node ID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `databases` | Database\[\] |  |
| `pagination` | object |  |
| `search` | object |  |

```bash
curl -X GET "$PANEL_URL/api/admin/databases" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Databases retrieved successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions

### GET `/api/admin/databases/{id}`

- Auth: Admin
- Permission: `admin.databases.view`
- Route name: `admin-databases-show`
- Controller: [`DatabasesController::show`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/DatabasesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/databases.php#L36)

**Get database by ID** Retrieve a specific database instance by its ID with associated node information. Password is excluded from response.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Database ID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `database` | Database |  |

```bash
curl -X GET "$PANEL_URL/api/admin/databases/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Database retrieved successfully · `400` Invalid ID format · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Database not found

### PATCH `/api/admin/databases/{id}`

- Auth: Admin
- Permission: `admin.databases.edit`
- Route name: `admin-databases-update`
- Controller: [`DatabasesController::update`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/DatabasesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/databases.php#L51)

**Update database** Update an existing database instance. Only provided fields will be updated.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Database ID |

Request body: [`DatabaseUpdate`](https://featherpanel.com/docs/api/schemas/#schema-databaseupdate) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | Database name |
| `node_id` | integer | no | Node ID |
| `database_type` | string | no | Database type |
| `database_port` | integer | no | Database port |
| `database_username` | string | no | Database username |
| `database_password` | string | no | Database password |
| `database_host` | string | no | Database host |
| `database_subdomain` | string | no | Optional custom hostname shown to users for database access |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X PATCH "$PANEL_URL/api/admin/databases/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","node_id":0,"database_type":"","database_port":0,"database_username":"","database_password":"","database_host":"","database_subdomain":""}'
```

Plugin events: [`featherpanel:admin:databases:database:updated`](https://featherpanel.com/docs/plugins/events/databases/#database-updated)

Responses: `200` Database updated successfully · `400` Bad request - Invalid data · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Database or node not found · `500` Internal server error - Failed to update database

### DELETE `/api/admin/databases/{id}`

- Auth: Admin
- Permission: `admin.databases.delete`
- Route name: `admin-databases-delete`
- Controller: [`DatabasesController::delete`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/DatabasesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/databases.php#L67)

**Delete database** Permanently delete a database instance. This action cannot be undone.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Database ID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X DELETE "$PANEL_URL/api/admin/databases/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:admin:databases:database:deleted`](https://featherpanel.com/docs/plugins/events/databases/#database-deleted)

Responses: `200` Database deleted successfully · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Database not found · `500` Internal server error - Failed to delete database

### PUT `/api/admin/databases`

- Auth: Admin
- Permission: `admin.databases.create`
- Route name: `admin-databases-create`
- Controller: [`DatabasesController::create`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/DatabasesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/databases.php#L83)

**Create new database** Create a new database instance. Health checks are skipped by default. Use /api/admin/databases/test-connection endpoint to test the connection before creating if needed. Node ID is optional for migration purposes.

Request body: [`DatabaseCreate`](https://featherpanel.com/docs/api/schemas/#schema-databasecreate) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Database name |
| `node_id` | integer | no | Node ID (optional) |
| `database_type` | string | yes | Database type |
| `database_port` | integer | yes | Database port |
| `database_username` | string | yes | Database username |
| `database_password` | string | yes | Database password |
| `database_host` | string | yes | Database host |
| `database_subdomain` | string | no | Optional custom hostname shown to users for database access |
| `id` | integer | no | Optional database ID (useful for migrations from other platforms) |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `database_id` | integer | ID of the created database |

```bash
curl -X PUT "$PANEL_URL/api/admin/databases" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","node_id":0,"database_type":"","database_port":0,"database_username":"","database_password":"","database_host":"","database_subdomain":"","id":0}'
```

Plugin events: [`featherpanel:admin:databases:database:created`](https://featherpanel.com/docs/plugins/events/databases/#database-created)

Responses: `201` Database created successfully · `400` Bad request - Invalid data · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Node not found (only if node\_id is provided) · `500` Internal server error - Failed to create database

### GET `/api/admin/databases/node/{nodeId}`

- Auth: Admin
- Permission: `admin.databases.view`
- Route name: `admin-databases-by-node`
- Controller: [`DatabasesController::getByNode`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/DatabasesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/databases.php#L94)

**Get databases by node** Retrieve all database instances for a specific node with pagination and search capabilities.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `nodeId` | path | integer | yes | Node ID |
| `page` | query | integer | no | Page number for pagination |
| `limit` | query | integer | no | Number of records per page |
| `search` | query | string | no | Search term to filter databases by name |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `databases` | Database\[\] |  |
| `pagination` | object |  |
| `search` | object |  |

```bash
curl -X GET "$PANEL_URL/api/admin/databases/node/$NODE_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Databases for node retrieved successfully · `400` Invalid node ID format · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Node not found

### GET `/api/admin/databases/{id}/health`

- Auth: Admin
- Permission: `admin.databases.view`
- Route name: `admin-databases-health-check`
- Controller: [`DatabasesController::healthCheck`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/DatabasesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/databases.php#L109)

**Check database health** Perform a health check on a specific database instance by testing the connection.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | integer | yes | Database ID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `database_id` | integer | Database ID |
| `healthy` | boolean | Whether the database is healthy |
| `message` | string | Health check message |
| `response_time` | number | Connection response time in milliseconds |

```bash
curl -X GET "$PANEL_URL/api/admin/databases/$ID/health" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Health check completed · `400` Invalid ID format · `401` Unauthorized · `403` Forbidden - Insufficient permissions · `404` Database not found

### POST `/api/admin/databases/test-connection`

- Auth: Admin
- Permission: `admin.databases.create`
- Route name: `admin-databases-test-connection`
- Controller: [`DatabasesController::testConnection`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/Admin/DatabasesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/admin/databases.php#L124)

**Test database connection** Test a database connection without creating a database record. Useful for validating connection parameters.

Request body: [`ConnectionTest`](https://featherpanel.com/docs/api/schemas/#schema-connectiontest) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `database_type` | string | yes | Database type |
| `database_port` | integer | yes | Database port |
| `database_username` | string | yes | Database username |
| `database_password` | string | yes | Database password |
| `database_host` | string | yes | Database host |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `success` | boolean | Whether the connection was successful |
| `message` | string | Connection test message |
| `response_time` | number | Connection response time in milliseconds |

```bash
curl -X POST "$PANEL_URL/api/admin/databases/test-connection" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"database_type":"","database_port":0,"database_username":"","database_password":"","database_host":""}'
```

Responses: `200` Connection test completed · `400` Bad request - Missing required fields · `401` Unauthorized · `403` Forbidden - Insufficient permissions