API Examples

API Examples shows the difference between a complete parameter template and one runnable request. Both use the real SHM Engine port 882.

Where to find it: Documentation > Hosting Manager > API > API Examples.

Available to: Anyone may read the examples. Running them requires an API identity allowed to call the chosen endpoint and target.

What this page does

Use these patterns to wire a client correctly. The endpoint cards remain the authoritative field-by-field reference because they contain every current key, accepted value, default, dependency, and source location.

Before you start

Replace every placeholder deliberately. Never paste a live key into documentation, browser JavaScript, screenshots, tickets, or shell history shared with other users.

Health check — no request parameters

curl -sS 'https://panel.example.com:882/v1/health' \
  -H 'X-Api-User: YOUR_API_USER' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Accept: application/json'

Read one DNS zone — every parameter included

This endpoint has one path parameter, domain, and no query or JSON keys.

curl -sS 'https://panel.example.com:882/v1/dns/zones/example.com' \
  -H 'X-Api-User: demo' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Accept: application/json'

Complete template for a conditional request

The storage-cleanup endpoint accepts four JSON keys. The template lists all four, but plan_token belongs to apply mode while actions and journal_retain_days belong to preview. Do not send incompatible branches merely because both are documented.

{
  "path_parameters": {},
  "query_parameters": {},
  "json_body": {
    "mode": "preview",
    "actions": ["package_cache", "journal", "temporary_files", "logs"],
    "journal_retain_days": 14,
    "plan_token": "RETURNED_BY_PREVIEW_FOR_APPLY_MODE"
  }
}

Runnable preview branch

curl -sS -X POST 'https://panel.example.com:882/v1/root/maintenance/storage-cleanup' \
  -H 'X-Api-User: root' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data '{"mode":"preview","actions":["package_cache","journal","temporary_files","logs"],"journal_retain_days":14}'

Server-side JavaScript read

const response = await fetch(
  'https://panel.example.com:882/v1/dns/zones/example.com',
  {
    method: 'GET',
    headers: {
      'X-Api-User': process.env.SHM_API_USER,
      'X-Api-Key': process.env.SHM_API_KEY,
      Accept: 'application/json'
    }
  }
);
const payload = await response.json();
if (!response.ok || payload.status === 'error') {
  throw new Error(payload.message || 'SHM API request failed');
}

Response handling

Read the HTTP status and JSON envelope. Preserve request_id when returned. After a mutation, call the corresponding read endpoint or open the owning SHM page and verify the customer-facing service.

How to use it

1. Start with the matching endpoint card.
2. Copy its complete template and remove keys that do not belong to the chosen conditional branch.
3. Replace placeholders with current ids and values.
4. Run a read or preview first where available.
5. Verify any mutation through a separate read.

Result and next check

The request reaches :882, contains every key required by its chosen branch, and returns a JSON result your client handles explicitly.