API Reference — V1

Complete reference for the Mado Hosting Reseller API. Manage servers, backups, files and more programmatically.

Base URL

https://www.mado-hosting.com/api/v1

Authentication

All API requests must include a valid API key in the Authorization header. API keys are prefixed with rsk_ and can be created in the Reseller Dashboard.

curl -X GET "https://www.mado-hosting.com/api/v1/servers" \
  -H "Authorization: Bearer rsk_your_api_key_here" \
  -H "Content-Type: application/json"

Response Format

All successful responses follow a consistent envelope with a data object. Paginated endpoints additionally include a pagination object.

Success

{
  "data": {
    "servers": [...]
  }
}

Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "name is required",
    "requestId": "req_abc123"
  }
}

Pagination

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 48,
    "totalPages": 2,
    "hasNext": true,
    "hasPrev": false
  }
}

Headers

Header	Description
`Authorization`	Required. Bearer token with API key. `Bearer rsk_...`
`Content-Type`	Required for POST/PUT/PATCH. `application/json`
`X-Request-Id`	Response header. Unique request ID for debugging.
`Idempotency-Key`	Optional. Prevents duplicate execution (24h cache).
`If-Match`	Optimistic locking for PATCH /servers/[id]. Pass version number.
`X-RateLimit-Limit`	Response. Maximum requests per window.
`X-RateLimit-Remaining`	Response. Remaining requests in current window.

Error Codes

All errors follow the same format with a machine-readable code and human-readable message.

HTTP	Code	Description
400	`VALIDATION_ERROR`	Invalid parameters or missing required fields
400	`LIMIT_EXCEEDED`	Quota/resource limit reached (backups, schedules, etc.)
400	`NO_CHANGE`	Resize to same size
400	`INVALID_RAM`	RAM not in valid increments (0.5GB)
400	`BELOW_MIN_RAM`	RAM below pricing minimum
400	`ABOVE_MAX_RAM`	RAM above pricing maximum
400	`RAM_LIMIT_EXCEEDED`	Total reseller RAM quota exceeded
400	`DISK_USAGE_EXCEEDED`	Cannot downgrade due to disk usage
401	`AUTH_REQUIRED`	Missing or invalid API key
403	`FORBIDDEN`	Insufficient permissions
403	`ADDON_REQUIRED`	Feature requires an addon or Premium plan
403	`FEATURE_UNAVAILABLE`	Feature not available for this plan
403	`DISTRIBUTION_RESTRICTED`	Mod does not allow third-party downloads
404	`SERVER_NOT_FOUND`	Server not found or does not belong to reseller
404	`USER_NOT_FOUND`	User not found (subuser)
404	`NOT_FOUND`	Resource not found at Pelican level
409	`CONFLICT`	Version mismatch or duplicate entity
409	`SERVER_SUSPENDED`	Server is suspended — write operations blocked
409	`SERVER_INSTALLING`	Server is still provisioning
409	`ALREADY_EXISTS`	Entity already exists (e.g. subuser)
422	`LIMIT_REACHED`	Pelican-level limit reached
500	`CONFIG_ERROR`	Server configuration missing (e.g. DB host)
500	`INTERNAL_ERROR`	Internal server error
500	`UPLOAD_FAILED`	Mod upload to server failed
503	`SERVICE_UNAVAILABLE`	No available nodes, ports, or panel unavailable