Databases API

PostgreSQL and MariaDB instances

Endpoints

Method	Path	Description
POST	/v1/databases	Create database
DELETE	/v1/databases	Delete database
DELETE	/v1/databases/{db_type}/{db_name}	Delete database
PATCH	/v1/databases/{db_type}/{db_name}	Update database
GET	/v1/databases/{db_type}	List databases by type
GET	/v1/databases/engines	List database engines
POST	/v1/databases/{db_type}/{db_name}/restart	Restart database
GET	/v1/databases/{db_type}/{db_name}/credentials	Get database credentials
POST	/v1/databases/{db_type}/{db_name}/credentials/rotate	Rotate database credentials
GET	/v1/databases/{db_type}/{db_name}/info	Get database info
POST	/v1/databases/{db_type}/{db_name}/firewall	Add firewall rule
GET	/v1/databases/{db_type}/{db_name}/firewall	List firewall rules
DELETE	/v1/databases/{db_type}/{db_name}/firewall/{rule_id}	Delete firewall rule
GET	/v1/databases/{db_type}/{db_name}/metrics	Get database metrics
GET	/v1/quota	Get database quota
GET	/v1/databases/history	List database history
POST	/v1/databases/{db_type}/{db_name}/snapshots	Create snapshot
GET	/v1/databases/{db_type}/{db_name}/snapshots	List snapshots
POST	/v1/databases/{db_type}/{db_name}/restore	Restore from snapshot
DELETE	/v1/databases/{db_type}/{db_name}/snapshots/{snapshot_id}	Delete snapshot
GET	/v1/databases/{db_type}/{db_name}/backup-policy	Get backup policy
PUT	/v1/databases/{db_type}/{db_name}/backup-policy	Set backup policy

POST /v1/databases

Create database

Create a new database (PostgreSQL or MariaDB)

This endpoint:

1. Authenticates the customer via API key
2. Checks database quota and permissions
3. Creates a database and user on the local server
4. Reports usage to the central server for billing
5. Returns connection details

Requires: 'database:create' permission

Special behavior for internal API keys:

• Internal keys can specify customer_id in request body to create databases on behalf of customers
• Regular customer keys can only create databases for themselves (customer_id override is ignored)

Request Body:

Field	Type	Description
db_type	string	Required. Database type (postgresql or mariadb) Values: postgresql, mariadb
requested_name	object	Optional custom database name suffix (alphanumeric and underscore only, max 30 chars). Creates deterministic name: cust_{customer_id}_
customer_id	object	Target customer ID (internal API keys only)

Example:

{
  "db_type": "postgresql",
  "requested_name": "webapp_prod_db",
  "customer_id": null
}

Response:

Field	Type	Description
success	boolean	Required.
db_type	string	Required.
db_name	string	Required.
username	string	Required.
password	string	Required.
host	string	Required.
port	integer	Required.
connection_string	string	Required.
message	string	Required.
password_generated	boolean	True if password was auto-generated
idempotent	boolean	True if database already existed (no new creation)

Example:

curl -X POST https://api.wayscloud.services/v1/databases \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

DELETE /v1/databases

Delete database

Delete a database (PostgreSQL or MariaDB)

This endpoint:

1. Authenticates the customer via API key
2. Checks permissions
3. Verifies database ownership
4. Deletes the database and optionally the user
5. Reports deletion to the central server

Requires: 'database:delete' permission and database ownership

Request Body:

Field	Type	Description
db_type	string	Required. Values: postgresql, mariadb
db_name	string	Required.
username	object

Example:

{
  "db_type": "postgresql",
  "db_name": "cust_6dd1d906_pg_webapp_prod_db",
  "username": "cust_6dd1d906_pg_webapp_prod_db"
}

Response:

Field	Type	Description
success	boolean	Required.
message	string	Required.

Example:

curl -X DELETE https://api.wayscloud.services/v1/databases \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

DELETE /v1/databases/{db_type}/

Delete database

Delete a database (RESTful endpoint with path parameters)

This is an alternative RESTful endpoint that accepts database info via URL path instead of request body. It calls the same underlying delete logic.

Args: db_type: Either 'postgresql' or 'mariadb' db_name: Database name (with customer prefix) username: Optional username to delete (query parameter)

Requires: 'database:delete' permission and database ownership

Response:

Field	Type	Description
success	boolean	Required.
message	string	Required.

Example:

curl -X DELETE https://api.wayscloud.services/v1/databases/{db_type}/{db_name} \
  -H "X-API-Key: YOUR_API_KEY"

---

PATCH /v1/databases/{db_type}/

Update database

Update database settings (scaling)

Currently supports:

• connection_limit: Adjust the maximum number of simultaneous connections
• description: Add or update a description/notes for this database

Other scaling options (RAM, storage) require support intervention as they involve infrastructure changes.

Request Body:

Field	Type	Description
connection_limit	object	Maximum connections allowed (10-1000)
description	object	Optional description/notes for this database

Example:

{
  "connection_limit": 200,
  "description": "Increased connection limit for production traffic"
}

Response:

Field	Type	Description
success	boolean
message	string

Example:

curl -X PATCH https://api.wayscloud.services/v1/databases/{db_type}/{db_name} \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

GET /v1/databases/

List databases by type

List all databases of a specific type

Args: db_type: Either 'postgresql' or 'mariadb' customer_id: Optional query parameter for internal keys to filter by specific customer

Requires: 'database:read' permission

Special behavior for internal API keys:

• Internal keys can specify customer_id query parameter to list databases for specific customer
• Regular customer keys can only list their own databases (customer_id parameter is ignored)

Response:

Field	Type	Description
db_type	string	Required.
databases	array	Required.

Example:

curl https://api.wayscloud.services/v1/databases/{db_type} \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/databases/engines

List database engines

List all supported database engines

Returns available database types with their versions and capabilities. Requires service API key.

Response:

Field	Type	Description
engines	array

Example:

curl https://api.wayscloud.services/v1/databases/engines \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/databases/{db_type}/{db_name}/restart

Restart database

Terminate all active connections to a database

This is useful when you need to force-disconnect all clients, for example before maintenance or schema changes.

Warning: This will immediately disconnect all active clients. Applications should be prepared to reconnect automatically.

Note: This doesn't restart the database server itself, only terminates connections to this specific database.

Response:

Field	Type	Description
success	boolean
message	string

Example:

curl -X POST https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/restart \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/databases/{db_type}/{db_name}/credentials

Get database credentials

Get database credentials metadata (without password)

Returns connection info for the database without exposing the password. To get a new password, use POST /credentials/rotate.

Security Note: This endpoint intentionally does NOT return the password. Passwords are only shown when first created or when rotated.

Args: db_type: Either 'postgresql' or 'mariadb' db_name: Database name (with customer prefix)

Requires: 'database:read' permission and database ownership

Response:

Field	Type	Description
host	string	Database server hostname
port	integer	Database port
database	string	Database name
username	string	Database username
password	string	Database password (only shown once at creation)
connection_string	string	Complete connection string

Example:

curl https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/credentials \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/databases/{db_type}/{db_name}/credentials/rotate

Rotate database credentials

Rotate database password and return new credentials

Generates a new secure password for the database user and updates it in both the database server and Vault.

Warning: This will invalidate the old password immediately. All existing connections using the old password will fail.

Args: db_type: Either 'postgresql' or 'mariadb' db_name: Database name (with customer prefix)

Returns: New credentials including the new password and connection string

Response:

Field	Type	Description
success	boolean	Required.
db_name	string	Required.
username	string	Required.
password	string	Required.
host	string	Required.
port	integer	Required.
connection_string	string	Required.
created_at	object

Example:

curl -X POST https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/credentials/rotate \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/databases/{db_type}/{db_name}/info

Get database info

Get detailed information about a database

Returns:

• Database size (MB)
• Current connection count
• Connection limit
• Owner
• Creation timestamp (if available from Vault)

Args: db_type: Either 'postgresql' or 'mariadb' db_name: Database name (with customer prefix)

Requires: 'database:read' permission and database ownership

Response:

Field	Type	Description
db_name	string	Required.
db_type	string	Required.
size_mb	object
connection_count	object
connection_limit	object
created_at	object
owner	object

Example:

curl https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/info \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/databases/{db_type}/{db_name}/firewall

Add firewall rule

Add an IP address to the firewall whitelist for a specific database

Creates a UFW firewall rule to allow the specified IP address to connect to this database. Rules are applied immediately at the network level.

Path Parameters:

• db_type: Database type (postgresql or mariadb)
• db_name: Technical database name (e.g., cust_abc123_pg_20251109_xyz)

Request Body:

• ip_address: IPv4 address or CIDR block (e.g., "192.168.1.1" or "10.0.0.0/24")
• description: Optional description for the rule

Note: The database must belong to the authenticated customer.

Request Body:

Field	Type	Description
ip_address	string	Required. IP address or CIDR block to whitelist
description	object	Optional rule description (e.g., 'Office network')

Example:

{
  "ip_address": "192.0.2.100/32",
  "description": "Office VPN connection"
}

Response:

Field	Type	Description
rule_id	string	Required. Unique rule identifier (UUID)
db_name	string	Required. Database name
db_type	string	Required. Database type
ip_address	string	Required. IP address or CIDR block
port	integer	Required. Database port
description	object	Optional rule description
created_at	string	Required.

Example:

curl -X POST https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/firewall \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

GET /v1/databases/{db_type}/{db_name}/firewall

List firewall rules

List all firewall rules for a specific database

Returns all IP addresses that are whitelisted for this database.

Path Parameters:

• db_type: Database type (postgresql or mariadb)
• db_name: Technical database name

Note: The database must belong to the authenticated customer.

Response:

Field	Type	Description
rules	array	Required.
total	integer	Required. Total number of rules

Example:

curl https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/firewall \
  -H "X-API-Key: YOUR_API_KEY"

---

DELETE /v1/databases/{db_type}/{db_name}/firewall/

Delete firewall rule

Remove a specific firewall rule from a database

Removes the UFW firewall rule and deletes it from the database. The rule is verified to be removed before updating the database.

Path Parameters:

• db_type: Database type (postgresql or mariadb)
• db_name: Technical database name
• rule_id: UUID of the firewall rule to delete

Note: The database must belong to the authenticated customer.

Response:

Field	Type	Description
success	boolean
message	string

Example:

curl -X DELETE https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/firewall/{rule_id} \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/databases/{db_type}/{db_name}/metrics

Get database metrics

Get performance metrics for a specific database

Returns storage usage, connection counts, and query statistics. Data is pulled from the central metrics database.

Note: Metrics are collected every 5 minutes by the background collector.

Response:

Field	Type	Description
database_id	string
storage_gb	number	Storage used in GB
backup_gb	number	Backup storage in GB
active_connections	integer	Current active connections
max_connections	integer	Maximum connections allowed
total_queries	integer	Total queries executed
queries_per_sec	number	Queries per second
cache_hit_ratio	number	Cache hit ratio percentage
cpu_percent	number	CPU usage percentage
memory_percent	number	Memory usage percentage
measured_at	string

Example:

curl https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/metrics \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/quota

Get database quota

Get database quota and usage summary for customer

Shows RAM allocation, storage usage, and estimated monthly cost.

Response:

Field	Type	Description
used	integer	Number of databases created
limit	integer	Maximum databases allowed
storage_used_gb	number
storage_limit_gb	number

Example:

curl https://api.wayscloud.services/v1/quota \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/databases/history

List database history

List database history (for billing and audit)

Shows all databases ever created by the customer, including deleted ones. Useful for billing reconciliation and audit purposes.

Response:

Example:

curl https://api.wayscloud.services/v1/databases/history \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/databases/{db_type}/{db_name}/snapshots

Create snapshot

Create a snapshot (backup) of a database

This creates an immediate backup of the database. Snapshots are stored on disk and can be restored later.

Args: db_type: Either 'postgresql' or 'mariadb' db_name: Database name (with customer prefix) request: Snapshot creation request (optional description)

Requires: 'database:read' permission and database ownership

Request Body:

Field	Type	Description
description	object	Optional description of snapshot

Example:

{
  "description": "Before major schema migration"
}

Response:

Field	Type	Description
success	boolean	Required.
snapshot_id	string	Required.
db_name	string	Required.
db_type	string	Required.
size_mb	object
created_at	string	Required.
description	object
message	string	Required.

Example:

curl -X POST https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/snapshots \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

GET /v1/databases/{db_type}/{db_name}/snapshots

List snapshots

List all snapshots for a database

Returns all snapshots (backups) created for this database, sorted by creation time (newest first).

Args: db_type: Either 'postgresql' or 'mariadb' db_name: Database name (with customer prefix)

Requires: 'database:read' permission and database ownership

Response:

Field	Type	Description
db_name	string	Required.
db_type	string	Required.
snapshots	array	Required.

Example:

curl https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/snapshots \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/databases/{db_type}/{db_name}/restore

Restore from snapshot

Restore a database from a snapshot

This replaces the current database contents with the snapshot. WARNING: This operation cannot be undone! Consider creating a snapshot first.

Args: db_type: Either 'postgresql' or 'mariadb' db_name: Database name (with customer prefix) request: Restore request (snapshot_id, optional target_db_name)

Requires: 'database:update' permission and database ownership

Request Body:

Field	Type	Description
snapshot_id	string	Required. Snapshot ID to restore from
target_db_name	object	Optional: Restore to new database name

Example:

{
  "snapshot_id": "snap_20251126_143000_a1b2c3d4",
  "target_db_name": "webapp_restored_db"
}

Response:

Field	Type	Description
success	boolean	Required.
db_name	string	Required.
snapshot_id	string	Required.
message	string	Required.

Example:

curl -X POST https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/restore \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

DELETE /v1/databases/{db_type}/{db_name}/snapshots/

Delete snapshot

Delete a snapshot

Permanently deletes a snapshot file from disk. This operation cannot be undone.

Args: db_type: Either 'postgresql' or 'mariadb' db_name: Database name (with customer prefix) snapshot_id: Snapshot ID to delete

Requires: 'database:delete' permission and database ownership

Response:

Field	Type	Description
success	boolean
message	string

Example:

curl -X DELETE https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/snapshots/{snapshot_id} \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/databases/{db_type}/{db_name}/backup-policy

Get backup policy

Get backup policy for a database

Returns the automated backup configuration for this database.

Args: db_type: Either 'postgresql' or 'mariadb' db_name: Database name (with customer prefix)

Requires: 'database:read' permission and database ownership

Response:

Field	Type	Description
db_name	string	Required.
db_type	string	Required.
enabled	boolean	Required.
frequency	string	Required.
retention_days	integer	Required.
time_of_day	object
last_backup	object
next_backup	object

Example:

curl https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/backup-policy \
  -H "X-API-Key: YOUR_API_KEY"

---

PUT /v1/databases/{db_type}/{db_name}/backup-policy

Set backup policy

Set backup policy for a database

Configure automated backups for this database.

Args: db_type: Either 'postgresql' or 'mariadb' db_name: Database name (with customer prefix) request: Backup policy configuration

Requires: 'database:update' permission and database ownership

Request Body:

Field	Type	Description
enabled	boolean	Required. Enable/disable automated backups
frequency	string	Backup frequency Values: hourly, daily, weekly
retention_days	integer	How many days to keep backups
time_of_day	object	Time for daily backups (HH:MM format)

Example:

{
  "enabled": true,
  "frequency": "daily",
  "retention_days": 7,
  "time_of_day": "02:00"
}

Response:

Field	Type	Description
db_name	string	Required.
db_type	string	Required.
enabled	boolean	Required.
frequency	string	Required.
retention_days	integer	Required.
time_of_day	object
last_backup	object
next_backup	object

Example:

curl -X PUT https://api.wayscloud.services/v1/databases/{db_type}/{db_name}/backup-policy \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---