Skip to main content

eEVOS HCI REST API – Getting Started and Reference

The REST API for eEVOS HCI automates product-specific administration. This documentation belongs to this product only; eEKAS, HA Cluster and eEVOS HCI have different API scopes.

Current reference and downloads

Edition: 23 October 2026. Version 1.0.0. 347 operations.

Product scope

Virtual machines (146 operations), Ceph (60), cluster administration (54), networking, hardware sensors, users, and iSCSI/NVMe initiators.

The eEVOS HCI reference is the API documentation for euronas-hci. Use this reference for VM and HCI automation; eEKAS S3/hosting documentation belongs to a different product.

Access and authentication

  1. Enable the REST API in the installed system administration and configure the appropriate management interface and API credential. New external configurations default to 127.0.0.1; remote clients need a reachable interface.
  2. Base URL: https://<server>:18443. Adjust the address and port to the actual configuration.
  3. Send the header X-API-Key: <API_KEY> with every protected request. Validate HTTPS certificates; for a private CA use --cacert /path/to/ca.pem.
  4. Send passwords, tokens, API keys and fencing credentials only in JSON request bodies, never in URLs. Content-Type: application/json.

First read-only requests

Replace the placeholders. Query product capabilities first, then status:

curl --fail-with-body -H 'X-API-Key: <API_KEY>' \
  'https://<server>:18443/api/v1/product/capabilities'

curl --fail-with-body -H 'X-API-Key: <API_KEY>' \
  'https://<server>:18443/api/v1/cluster/status'

curl --fail-with-body -H 'X-API-Key: <API_KEY>' \
  'https://<server>:18443/api/v1/vms'

Reliable automation

  • For retryable POST, PUT, PATCH and DELETE requests, use a unique Idempotency-Key. Reuse that key when retrying the same operation. Cluster bootstrap and join require this header.
  • HTTP 202 acknowledges acceptance only. Poll the returned status_url until completion; do not treat acceptance as successful completion.
  • X-Correlation-ID from responses should be retained for tracing. Do not log API keys or other secrets.

Error handling

HTTP Meaning / action
400 / 422 Check input and parameters; secrets in URLs are rejected.
401 / 403 Check the API key or role permissions.
409 Conflict with current state; inspect state before retrying.
428 Required Idempotency-Key is missing.
429 / 503 Rate or capacity limit. Back off and honor Retry-After when returned.
501 Operation is not supported by this product.

Reference for the installed version

Availability depends on the installed release and enabled features. When documentation is enabled, authorized API clients can access /api/docs, /api/openapi.json and /api/openapi.yaml at the configured API endpoint. These resources require a valid API key. Use the operations supported by the installed system.

Use and support

API usage is at your own responsibility and is not covered by support. Test automation with suitable test resources and follow the prerequisites of each operation.

Back to top