Skip to main content

REST API – Getting Started and Automation

The eEKAS REST API lets you retrieve status information and automate recurring administrative tasks. This introduction covers setup and a first read-only request. The API reference in this chapter describes individual operations.

Usage and support: API usage is at your own responsibility and is not covered by support.

Configure API access

  1. Open the system settings in the eEKAS web administration interface and select the REST API settings. Enable the API.
  2. Select the management network, HTTPS and API port. The default port is 18443. Each cluster node uses its own address on the selected network. Restrict network access to the management clients that need it.
  3. Configure an API username and API key. For a new key, you can leave the key field empty to generate a secure key; an existing key can be retained. Store the key in a protected secret store.
  4. Select the least privileged role that meets your needs. Use read-only for status queries; s3-admin is intended for S3 administration. Check both operation availability and role permissions.
  5. Set a credential expiration date if needed. Review the request rate limit and retention period for idempotency responses.
  6. Enable OpenAPI and Swagger UI if you need the reference for your installation. These documentation endpoints also require a valid API key.
  7. Save the API settings. Selecting the cluster option applies the configuration and restarts the API on every cluster node. Check connectivity to the nodes your clients will use.

Use a DNS name that matches the HTTPS certificate. For a private certificate authority, provide the CA file to your client. Keep certificate validation enabled. CORS is only needed for browser applications calling from another origin; curl and server-side scripts do not require it.

Your first status request

Replace the hostname and key with your values. This example reads S3 status without changing configuration. Run it on your management client; it does not require administrator privileges on that client.

curl --silent --show-error --fail-with-body --include   --header 'X-API-Key: <API_KEY>'   'https://eekas.example.com:18443/api/v1/s3/status'

For a private CA, add --cacert /path/to/ca.pem. Keep real keys out of shared scripts, source control, terminal history and logs. Production automation should load the key from a protected secret store or a client configuration readable only by its execution account.

Retain the returned X-Correlation-ID header to match a request to diagnostic information. Send the API key in the X-API-Key header. S3 Access Keys and Secret Keys are separate credentials used by the S3 protocol.

Run changes reliably

  • Check the method, required fields, role and prerequisites in the reference for your installed version. Test mutating requests with test resources first.
  • Send passwords, secret keys, tokens and other secret parameters in a JSON request body with Content-Type: application/json. Secret values in URLs are rejected.
  • Use a unique Idempotency-Key for each logical operation that may be retried. Retry the same operation with the same key and identical request; use a new key for a new operation. Response retention is limited. Cluster membership changes require this header.
  • HTTP 202 means a background operation was accepted, not successfully completed. Store the returned job identifier and poll GET /api/v1/jobs?job_id=<JOB_ID> until the job finishes. Check its result and the actual resource state.
  • After a connection failure, check the job or resource state before retrying a change.

Handle responses and errors

HTTP status Action
200 / 201 Check the response and result; 201 usually indicates a created resource.
202 Track the background job to completion.
400 / 422 Correct parameters, JSON content or prerequisites.
401 / 403 Check the API key, expiration and role permissions.
404 / 405 Check the path, resource, HTTP method and whether documentation is enabled.
409 Resolve the conflict with current system state.
428 Supply the required Idempotency-Key.
429 / 503 Reduce the request rate and honor Retry-After if present. Use controlled retries with backoff.
500 Capture the error and correlation ID; check the state before retrying.

Error responses include a JSON error field. Log the status, operation, time and correlation ID without storing secret headers or request bodies.

Automate S3 replication and backup

The reference includes read-only queries at GET /api/v1/object-storage/replication and GET /api/v1/object-storage/replication/backups. Mutating actions, invitations, recovery and confirmation fields are described in the API reference and companion S3 workflows guide.

Operational prerequisites also apply to API calls: an empty replication destination, certificate trust, isolation of the old primary, verified recovery points and WORM protection. Read S3 replication and recovery and SMB shares with S3 WORM for these requirements.

Reference and version

The complete reference covers 285 operations as of 8 October 2026. Find it in the REST API and Automation chapter. Use the OpenAPI specification served by your installation to check supported operations. Revalidate your automation after an eEKAS update.

Back to top