Servers

List, create, retrieve, update and delete servers.

GET/servers

List all reseller servers with pagination and filters.

Query Parameters

Name	Type	Required	Description
`page`	number	No	Page number (default: 1)
`limit`	number	No	Items per page, max 100 (default: 50)
`sort`	string	No	Sort: createdAt, name, ramGb, status (default: createdAt)
`order`	string	No	Direction: asc or desc (default: asc)
`status`	string	No	Filter by status
`game`	string	No	Filter by game
`search`	string	No	Search server name (contains)

curl "https://www.mado-hosting.com/api/v1/servers?page=1&limit=10&sort=name&order=asc" \
  -H "Authorization: Bearer rsk_your_key"

POST/servers

Create a new server. Returns 202 (server is provisioning).

Body Parameters

Name	Type	Required	Description
`name`	string	Yes	Server name (max 100 chars)
`ramGb`	number	Yes	RAM in GB (positive, 0.5GB increments)
`game`	string	No	Game ID (default: minecraft-java)
`gameType`	string	No	Game flavor (default: paper)
`gameVersion`	string	No	Game version (default: 1.21.4)
`planTier`	string	No	budget or premium (default: premium)
`addons`	AddonSelection[]	No	Array of addon selections
`externalReference`	string	No	External reference ID (max 255 chars)

curl -X POST "https://www.mado-hosting.com/api/v1/servers" \
  -H "Authorization: Bearer rsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Server",
    "ramGb": 4,
    "game": "minecraft-java",
    "gameType": "paper",
    "planTier": "premium",
    "addons": [{ "addon": "plugin-installer", "selected": true }]
  }'

The server is provisioned asynchronously. Status may briefly be PROVISIONING after creation.

GET/servers/:id

Get server details including limits, addons, and version number.

curl "https://www.mado-hosting.com/api/v1/servers/srv_abc123" \
  -H "Authorization: Bearer rsk_your_key"

PATCH/servers/:id

Update server (RAM, disk, external reference). Supports optimistic locking with If-Match.

Headers

Name	Type	Required	Description
`If-Match`	string	No	Version number for optimistic locking

Body Parameters

Name	Type	Required	Description
`ramGb`	number	No	New RAM in GB (positive)
`diskGb`	number	No	New disk in GB (positive)
`externalReference`	string	No	External reference (max 255 chars)

curl -X PATCH "https://www.mado-hosting.com/api/v1/servers/srv_abc123" \
  -H "Authorization: Bearer rsk_your_key" \
  -H "Content-Type: application/json" \
  -H "If-Match: 1" \
  -d '{ "ramGb": 8 }'

DELETE/servers/:id

Permanently delete a server. Removes from panel, SFTP, and DNS.

curl -X DELETE "https://www.mado-hosting.com/api/v1/servers/srv_abc123" \
  -H "Authorization: Bearer rsk_your_key"

This action is irreversible. All server data, backups, and DNS records will be deleted.

Error Codes

HTTP	Code	Description
400	`VALIDATION_ERROR`	Invalid parameters
404	`SERVER_NOT_FOUND`	Server not found
409	`CONFLICT`	Version mismatch (If-Match)
503	`SERVICE_UNAVAILABLE`	No available nodes/ports