Eyeglass API Guide

Introduction

The Eyeglass REST API offers an alternative way to interact with Eyeglass, complementing the web UI. Through the API, you can retrieve information such as replication policies, storage nodes, jobs, and alarms, and perform operations such as initiating a failover. The API Explorer includes a CURL builder for generating commands, which can be used in scripts to automate these operations. Token-based authentication secures and authorizes API requests.

Technical knowledge required: RESTful APIs, CURL, token-based authentication, core Eyeglass concepts (replication policies/relationships, nodes, jobs, alarms), JSON.

Common use cases:

• Polling alarms for a custom monitoring dashboard
• Building a status dashboard for replication/failover readiness
• Automating failover requests from external tooling
• Custom scripting, including triggering the Eyeglass Script Engine after a failover

API Tokens

A valid token must be included with every API request.

Creating a Token

1. Open the Eyeglass main menu, select the Superna Eyeglass REST API icon (requires an Enterprise license).
2. Select API Tokens > Create New Token.
3. Enter a name that identifies the calling application (for example, SRM for a VMware SRM integration) — this makes it possible to trace a given failover request back to the script or integration that issued it.
4. The new token appears in the token list, ready to copy.

Revoking a Token

Open the same API Tokens tab and select the X/Revoke control next to the token. A revoked token immediately loses access.

API Explorer

The API Explorer tab lets you browse available nodes, replication policies, and zones, and builds the corresponding CURL command as you make selections — useful both for testing and for generating commands to use in scripts.

Authentication

Include an HTTP header named api_key with a valid, unrevoked token on every request:

curl --header "api_key: <your-token>" --header "accept: application/json" https://<eyeglass-ip>/sera/v1/jobs

Endpoints

Both the /v1/ and /v2/ API families are current. /v2/ endpoints are the actively developed surface (failover jobs, DR test/rehearsal jobs, readiness, replication); /v1/ endpoints remain supported for jobs, alarms, healthcheck, and nodes.

Jobs (v2)

Method	Endpoint	Description
GET / POST	/v2/jobs/failover	List or create failover jobs.
POST	/v2/jobs/failover/drtest	Create a DR test job.
POST	/v2/jobs/failover/rehearsal	Create a DR rehearsal job.
DELETE / GET	/v2/jobs/failover/{id}	Cancel or retrieve a specific failover job.
GET	/v2/jobs/failover/{id}/log	Retrieve the failover log for a specific job.
GET / POST	/v2/jobs/readiness[/{id}]	Retrieve or trigger a DR readiness job.
GET / POST	/v2/jobs/replication[/{id}]	Retrieve or trigger a replication configuration job.

Alarms (v1)

Method	Endpoint	Description
GET	/v1/alarms/active	Retrieve currently active alarms.
GET	/v1/alarms/historical	Retrieve historical alarms. Supports since, until, and limit query parameters (epoch timestamps).

Example:

curl --header "api_key: <your-token>" "https://<eyeglass-ip>/sera/v1/alarms/historical?since=1499189000&until=1499190943&limit=50"

Healthcheck (v1)

Method	Endpoint	Description
GET	/v1/healthcheck	Retrieve the timestamp of the latest appliance health check.

Jobs (v1)

Method	Endpoint	Description
GET / POST	/v1/jobs	List or create a failover job.
GET	/v1/jobs/{id}	Retrieve a specific job.
GET	/v1/jobs/{id}/log	Retrieve the log for a specific job.

POST /v1/jobs parameters:

Parameter	Default	Description
sourceid	—	Source node/cluster ID.
targetid	—	Target node/cluster ID.
failovertarget	—	The replication policy or zone/pool ID to fail over.
pool	—	Target IP pool, if applicable to your platform's failover type.
controlled	true	Perform a controlled failover (fails over current data rather than the last replicated snapshot).
datasync	true	Sync data between source and target before failing over.
configsync	false	Sync configuration between source and target during failover.
resyncprep	true	Prepare the environment so failback can be performed later. Disable only if you don't intend to fail back using Eyeglass.
disablemirror	false	Skip creating the reverse/mirror replication relationship on the target.
quotasync	true	Sync quota settings between source and target.
blockonwarnings	true	Stop the failover from proceeding if a warning-level readiness status exists.
rollbackrenameshares	true	Revert any renamed shares if the failover fails.
smbdataintegrity	false	Disconnect active SMB sessions and block new ones on the source before failover begins.

note

Not every parameter applies to every storage platform's failover type — see Execute Failover with DR Assistant for which options are available per platform in the guided UI. The API accepts the same underlying set of options as the UI wizard.

Nodes (v1)

Method	Endpoint	Description
GET	/v1/nodes	List all managed storage clusters/nodes.
GET	/v1/nodes/{id}	Retrieve a specific node.
GET	/v1/nodes/{id}/policies[/{name}]	List or retrieve replication policies/relationships for a node.
GET	/v1/nodes/{id}/pools[/{name}]	List or retrieve IP pools for a node, where applicable.
GET	/v1/nodes/{id}/zones[/{name}]	List or retrieve zones for a node, where applicable to your platform.

Add foreadiness=true to a policy, pool, or zone GET request to retrieve full DR-readiness validation detail (equivalent to what's shown on the DR Dashboard in the UI) rather than just a summary status.

Error Models

Model	Field	Type	Description
ErrorModel	code	Integer	Error code.
	message	String	Error message description.
Job	failoverTarget	Job_failoverTarget	The zone/policy combination being failed over.
	finished	Long	Completion timestamp.
	id	String	Job ID.
	jobType	String	zone_failover | policy_failover
	name	String	Job name.
	sourceNode	Node	Source node.
	started	Long	Start timestamp.
	success	Boolean	Whether the job succeeded.
	targetNode	Node	Target node.
Node	id	String	Node/cluster ID.
	ip	String	Node IP address.
	name	String	Node name.
Policy	failoverReadiness	String	ok | warning | error
	id	String	Policy/replication relationship ID.
	name	String	Replication policy or relationship name.
	target	Node	Target node.
	zone	Zone	Associated zone, where applicable.
Zone	failoverReadiness	String	ok | warning | error
	id	String	Zone ID.
	name	String	Zone name.
Job_failoverTarget	zone	Zone	Associated zone.
	policies	array[Policy]	Associated policies.

Example: Build a Failover Automation Gateway

The API is commonly used to build a lightweight proxy application that lets other tools or teams trigger a scoped failover without direct Eyeglass GUI or token access — for example, integrating with VMware SRM, a custom monitoring dashboard, or an internal self-service portal.

note

This is a starting-point pattern, not a supported product. Build and test any automation against your own environment before relying on it operationally.

Pattern:

1. Generate an API token in Eyeglass for the automation (see API Tokens above).

2. Use GET /v1/nodes to retrieve your storage cluster/node IDs, then GET /v1/nodes/{id}/policies and /zones to retrieve the replication policies and zones available for failover.

3. Build a small web application (for example, a Node.js service behind an Nginx reverse proxy) that maps a scoped API key to specific failoverTarget values it's authorized to trigger — for example:

   {
     "eyeglassIp": "192.168.1.140",
     "apiKeys": {
       "key-1": [
         { "targetId": "<target-node-id>", "sourceId": "<source-node-id>", "failoverTarget": "<replication-relationship-name>" }
       ]
     }
   }

4. Expose two endpoints from your gateway application:

   • A failover-trigger endpoint that validates the caller's key against the authorized failoverTarget list, then issues the corresponding POST to /v1/jobs or /v2/jobs/failover.
   • A status endpoint that proxies GET /v1/jobs/{id} or /v2/jobs/failover/{id} so the caller can poll job progress.

5. Put the gateway behind HTTPS (a reverse proxy such as Nginx works well for this) so the Eyeglass API token itself is never exposed to the calling application.

Example: VMware SRM Integration

A common integration pattern is adding a custom command to a VMware Site Recovery Manager (SRM) recovery plan that calls the Eyeglass API (directly, or via a gateway as described above) via curl as part of the recovery workflow. When configuring this, increase the SRM callout command timeout (<calloutCommandLineTimeout> in vmware-dr.xml) to comfortably exceed your expected failover duration, since the default timeout is often too short for a storage failover to complete.

See Also

• Execute Failover with DR Assistant — the guided UI equivalent of the failover job API, including which Failover Options are available per storage platform.
• Eyeglass CLI Commands — command-line equivalents for common administrative tasks.