API Reference

Customer API endpoints, permissions, pagination, response fields, examples, and troubleshooting.

All server-data endpoints use the base URL below, require Authorization: Bearer YOUR_TOKEN, and return JSON.

https://maximushost.com/api/v1

Timestamps are ISO 8601 UTC strings such as 2026-01-15T12:34:56+00:00, or null when the value is not available.

GET /

Returns a small discovery response without requiring a token:

{
  "name": "MaximusHost Customer API",
  "version": "v1",
  "read_only": true,
  "documentation_url": "https://maximushost.com/wiki/customer-api/"
}

GET /servers

Lists servers owned by the token's account and servers actively shared with that account.

Optional query parameters:

page — page number; default 1, minimum 1, maximum 10000.
per_page — items per page; default 20, minimum 1, maximum 50.

Example response:

{
  "items": [
    {
      "id": 12345,
      "name": "Example Server",
      "type": "minecraft-java",
      "runtime": {
        "state": "running",
        "desired_state": "running",
        "updated_at": "2026-01-15T12:34:56+00:00"
      },
      "lifecycle": {
        "version": 1,
        "provisioning_state": "ready"
      },
      "connections": [
        {
          "key": "primary",
          "label": "Java",
          "address": "example.maximushost.com",
          "protocol": null,
          "public_port": null
        }
      ],
      "access": {
        "role": "owner",
        "permissions": ["owner"]
      },
      "resources": {
        "ram_gb": 4,
        "cpu_cores": 2
      }
    }
  ],
  "page": 1,
  "per_page": 20,
  "has_more": false
}

connections includes customer-facing connection addresses only. resources is included for an owner or for a shared member with viewresources, manageresources, or view_console; otherwise it is omitted.

GET /servers/{id}

Returns the same server-summary object shown in the list response for one numeric server ID. The account must own the server or have an active Server Team share.

curl --request GET \
  --url 'https://maximushost.com/api/v1/servers/12345' \
  --header 'Authorization: Bearer mhca_example_token_replace_me'

If the server ID is unknown or inaccessible, the API returns HTTP 404 with servernotfound. This intentionally does not reveal whether another customer's server exists.

GET /servers/{id}/resources

Returns recorded CPU and memory samples for a numeric server ID, newest first. It accepts page and per_page as described above.

The owner can read resources. A shared member needs viewresources, manageresources, or view_console.

$headers = @{ Authorization = 'Bearer mhca_example_token_replace_me' }

Invoke-RestMethod -Method Get `
  -Uri 'https://maximushost.com/api/v1/servers/12345/resources?page=1&per_page=20' `
  -Headers $headers

{
  "items": [
    {
      "memory_used_mb": 1536,
      "memory_limit_mb": 4096,
      "cpu_percent": 28.5,
      "recorded_at": "2026-01-15T12:34:56+00:00"
    }
  ],
  "page": 1,
  "per_page": 20,
  "has_more": false
}

Without the required resource permission, this endpoint returns HTTP 403 with forbidden.

GET /servers/{id}/incidents

Returns non-dismissed incident records for a numeric server ID, newest first. It accepts page and per_page.

The owner can read incidents. A shared member needs view_console.

import os
import requests

response = requests.get(
    'https://maximushost.com/api/v1/servers/12345/incidents',
    headers={'Authorization': f"Bearer {os.environ['MAXIMUSHOST_API_TOKEN']}"},
    params={'page': 1, 'per_page': 20},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Abbreviated response:

{
  "items": [
    {
      "id": 987,
      "server_id": 12345,
      "server_type": "minecraft-java",
      "incident_type": "unexpected_exit",
      "runtime_state": "stopped",
      "exit_code": 1,
      "oom_killed": false,
      "restart_count": 0,
      "message": "Server stopped unexpectedly.",
      "occurred_at": "2026-01-15T12:34:56+00:00",
      "created_at": "2026-01-15T12:34:57+00:00",
      "resolved_at": null,
      "dismissed_at": null,
      "diagnostic_history": [],
      "timeline": []
    }
  ],
  "page": 1,
  "per_page": 20,
  "has_more": false
}

An incident can include its id, serverid, servertype, incidenttype, runtimestate, exitcode, oomkilled, restartcount, message, timestamps, and structured diagnostic, diagnostichistory, reason, and timeline information. Internal incident fields such as the event key, node name, email-notification time, and dismissal actor are not returned.

If the current account lacks Console access, the endpoint returns HTTP 403 with forbidden. An empty items array means there are no non-dismissed incident records to return.

GET /servers/{id}/activity

Returns safe activity history for a numeric server ID, newest first. It accepts page and per_page. The owner and any active shared member can read activity.

curl --request GET \
  --url 'https://maximushost.com/api/v1/servers/12345/activity?page=1&per_page=20' \
  --header 'Authorization: Bearer mhca_example_token_replace_me'

{
  "items": [
    {
      "action": "server.start",
      "outcome": "success",
      "summary": "Server start requested",
      "source": "web",
      "metadata": {},
      "recorded_at": "2026-01-15T12:34:56+00:00"
    }
  ],
  "page": 1,
  "per_page": 20,
  "has_more": false
}

Activity actions use their canonical dotted identifiers, such as server.start, server.resources.update, and team.permissions.update. Activity metadata uses a small customer-safe allowlist: an actor role, a safe reason code, or a resource size when present. The response does not return request bodies, console commands, file contents, credentials, tokens, raw IP addresses, internal correlation identifiers, or other unapproved metadata.

Errors and troubleshooting

Customer API errors include a code, message, HTTP status, and API version information.

HTTP 401 with unauthenticated — the Authorization: Bearer header is missing. Add the header to the request.
HTTP 401 with invalid_token — the token is invalid, revoked, or malformed. Create a replacement in API Access if needed.
HTTP 403 with forbidden — the account does not have the required shared-server permission for the requested data. Ask the server owner to update the Server Team share.
HTTP 404 with servernotfound — the server ID is unknown or inaccessible for GET /servers/{id}. Confirm the numeric ID and current access.
HTTP 429 with rate_limited — the token exceeded 120 authenticated requests in 60 seconds. Wait before retrying.

For paginated endpoints, use whole-number page and perpage values. Values outside the supported ranges are constrained to the API's minimum or maximum, so check the returned page and perpage values when troubleshooting a surprising result.

Read-only guarantee

Bearer tokens for this Customer API can only read the endpoints on this page. They cannot start, stop, restart, configure, resize, or delete a server, and they cannot change files, backups, schedules, or billing.

MaximusHost Wiki