Zerto API Quickstart

A small, opinionated set of working examples for the Zerto v10.8 REST API, in bash + curl, Python, and PowerShell — one folder per appliance flavor.

New to REST APIs? Read GETTING-STARTED.md first — a 20-minute narrated walkthrough that takes you from "what's an API" all the way through creating a VPG and watching it finish.

If you've called REST APIs before and just want to skim, pick the folder that matches your environment and start with that folder's examples/01-get-token.

Pick your platform

Folder	Use this if…
zca-aws/	You have a Zerto Cloud Appliance running in AWS. Recovery target is EC2 (launch templates, subnets, instance types).
zca-azure/	You have a Zerto Cloud Appliance running in Azure. Recovery target is Azure VMs (resource groups, vnets/subnets, disk SKUs).
zvm-vmware/	You have an on-prem Zerto Virtual Manager managing a vCenter. Recovery target is vSphere (host clusters, datastores, port groups).

All three folders are fully independent — copy whichever one(s) you need into your own repo, ignore the rest.

What's the same across all three platforms

The Zerto v10 API is genuinely unified — same paths, same auth model, same response shapes. Specifically:

• Auth. All three appliance types authenticate with OAuth bearer tokens issued by the appliance's embedded Keycloak. The default in .env.example is the production zerto realm + zerto-client client — change to master + admin-cli if your install is a lab/PoC that uses the built-in Keycloak admin realm.
• Base URL. Always https://<host>/v1/... on TCP 443.
• API shape. All ~170 endpoints (alerts, VPGs, VRAs, peer sites, tasks, events, settings, log collector, configuration service, upgrade) are present on every appliance type, with identical request / response schemas.
• Task model. Most write operations return a task identifier immediately and do the actual work asynchronously — poll /v1/tasks/{id} to know when it's done.

What's different per platform

Almost entirely contained in examples/06-create-vpg:

• ZCA-AWS populates recovery.publicCloud.failover.aws with a launch template ID, subnet ID, and EC2 instance type.
• ZCA-Azure populates recovery.publicCloud.failover.azure with a resource group, subnet (full ARM resource ID), disk SKU, and Azure VM size.
• ZVM-VMware populates recovery.defaultHostClusterIdentifier and recovery.defaultDatastoreIdentifier with vCenter object UUIDs, plus a journal.datastoreIdentifier.

The discovery endpoints under /v1/virtualizationsites/{id}/... (hosts, clusters, datastores, networks, folders, resource pools) return whatever objects make sense for the underlying platform, so the same endpoint serves all three.

Important conceptual gotcha: the recovery block shape is determined by where the VPG recovers to, not which appliance you point your script at. A VPG that protects an AWS workload but recovers into a vCenter uses the vSphere recovery body even though you POSTed it to the AWS ZCA. The per-platform scripts here are written for the common "protect into the named platform" direction; for cross-platform flows, mix-and-match the recovery block from the appropriate folder.

What each example does (same in every folder)

#	Example	What it shows
01	01-get-token	OAuth password-grant against the appliance's Keycloak. Foundation for everything else.
02	02-list-vpgs	GET /v1/vpgs — VPG name, status, sub-status, actual RPO.
03	03-list-vras	GET /v1/vras — VRA status, protected/recovery counts.
04	04-list-alerts	GET /v1/alerts?isDismissed=false — active alerts only.
05	05-list-peer-sites	GET /v1/peersites — paired sites you can replicate to.
06	06-create-vpg	Two-step create: POST /v1/vpgSettings → POST .../commit. The body is platform-specific.
07	07-monitor-task	Polling pattern for GET /v1/tasks/{id} until terminal state.

Every example folder ships three runnable scripts:

example-name.sh    # bash + curl
example_name.py    # Python (requests)
Example-Name.ps1   # PowerShell 7+

Plus a per-example README.md explaining the endpoint, useful query parameters, and adjacent endpoints.

Conventions across the repo

• Self-signed certs are skipped (-k / verify=False / -SkipCertificateCheck). Remove these flags if you have a properly signed cert.
• Env vars from .env. The bash and Python examples auto-load <platform>/.env if it exists. PowerShell expects environment variables set in the session.
• No external runtime deps beyond what's already standard:
  • bash: curl, jq
  • Python: requests
  • PowerShell: 7+ (for -SkipCertificateCheck)
• No retry / refresh logic. Sessions are short-lived (~60s) — for long-running scripts, wrap calls and re-auth on 401.

What this repo is not

• A production SDK. These are read-the-source quickstart examples, not a robust client library. If you need a real client, this is a starting point — add token refresh, structured error handling, and retry logic.
• Exhaustive. The Zerto API has ~170 endpoints. These examples exercise the ~10 you'll hit first. Use the on-appliance Swagger UI (https://<host>/swagger) for the rest.

Testing

Every example in this repo has been executed end-to-end against live appliances. Summary of the most recent run:

• Date: 2026-04-30
• Zerto versions exercised: ZVM 10.8.0 · ZCA-AWS 10.8.10 · ZCA-Azure 10.8.10
• Platforms covered: on-prem vSphere ZVM, AWS ZCA, Azure ZCA
• Languages covered: bash + curl, Python 3, PowerShell 7

Read-only suite (01–05):

Script	bash	python	powershell
01-get-token	✓	✓	✓
02-list-vpgs	✓	✓	✓
03-list-vras	✓	✓	✓
04-list-alerts	✓	✓	✓
05-list-peer-sites	✓	✓	✓

Write / async-task suite (06–07) exercised in three directions to cover the recovery-shape variants:

Test scenario	Outcome
ZVM → ZCA-Azure (publicCloud body)	VPG committed, entered Sync state, deleted
ZCA-AWS → ZVM (vSphere body)	VPG committed, entered Sync state, deleted
ZCA-Azure → ZVM (vSphere body)	VPG committed, entered Initial Sync, deleted

Issues found during testing were folded back into the scripts and the per-example READMEs:

• The Keycloak password-grant requires scope=openid for the issued JWT to validate at /v1/* — added to all auth scripts and docs.
• AWS / Azure ZCAs enforce a minimum rpoInSeconds of 600 (vs. ZVM's 300); default in 06-create-vpg bumped to 600 across all three folders.
• vmInstanceType must accommodate the protected VM's vCPU count; documented with the exact error string.
• A vSphere recovery target requires networks.failover.hypervisor.defaultNetworkIdentifier to be set, otherwise commit fails with "null NetworkSettings.RecoveryNetwork"; documented with the PUT payload.
• commit returns a compound task identifier (<task-uuid>.<site-uuid>), not a plain UUID; documented.

License

GNU General Public License v3.0. See LICENSE for the full text, or https://www.gnu.org/licenses/gpl-3.0.html.