If you have automated Nutanix before, you have probably written against the v2.0 API on Prism Element or the v3 API on Prism Central. The v4 APIs are neither of those. They are a ground-up rewrite, and Nutanix now positions v4 as the recommended API for new work.
The good news is that once you understand the request shape, every v4 endpoint looks the same. This post covers that shape, how to authenticate, and how to get a first successful response.
Applies to: Prism Central v4 GA APIs. Namespace availability is release-dependent, so confirm the supported version for your Prism Central and AOS build before writing production code.
Which API version should you be using?: Nutanix currently ships several API generations side by side. Knowing which one you are looking at saves a lot of confusion when reading older blog posts and scripts.
| Version | Where it runs | Status |
|---|---|---|
| v4 | Prism Central | Recommended for new automation |
| v3 | Prism Central | Legacy, supported until formal deprecation |
| v2.0 | Prism Element | Legacy, cluster-local operations |
The practical rule: reach for v4 first, and fall back to a legacy API only when the function you need is not yet exposed in v4.
The shape of a v4 request: Every v4 endpoint is built from the same four parts: the Prism Central endpoint, a fixed /api prefix, a namespace, an API version, and the resource path.
The namespace is the part that trips up newcomers. Rather than one monolithic API, v4 splits functionality into domains, and you must know which domain owns the entity you want.
| Namespace | Commonly used for |
|---|---|
| vmm | Virtual machines, images, templates |
| clustermgmt | Clusters, hosts, storage containers |
| networking | Subnets, virtual switches, VPCs |
| iam | Users, roles, authorization policies |
prism | Tasks, categories, batch operations |
| dataprotection | Recovery points and protection policies |
One historical note worth knowing: the separate storage namespace was deprecated, and storage operations moved into clustermgmt. If you find an older example calling a storage endpoint, that is why it no longer resolves.
Authenticating the first call: For a first call, HTTP basic authentication with a Prism Central user is the fastest route. Encode username:password and send it in the Authorization header.
This is fine for exploration. It is not what you should end up with in production, for two reasons: the credentials belong to a human, and when Prism Central is integrated with an external directory, every request drives an authentication lookup against that directory. Later in this series, we will cover service accounts and API keys, which exist specifically for automation.
Your first request: A list request is the safest place to start, because it changes nothing.
AUTH=$(printf 'admin:password' | base64)
curl -X GET \
'https://pc.example.com:9440/api/vmm/v4.0/ahv/config/vms?$limit=5' \
-H 'Accept: application/json' \
-H "Authorization: Basic $AUTH"Note the $limit parameter. The v4 APIs use OData query conventions, and constraining the result set from the very first call is a good habit; a production Prism Central may be managing thousands of VMs.
In a lab, you may need –insecure if Prism Central is still using its self-signed certificate. Understand what that flag disables before carrying it into anything that matters.
Reading the response: A v4 response wraps the payload in a consistent envelope. The parts you will use constantly are:
- data: the entity or array of entities you asked for
- metadata: result counts, flags, and links
- extId: the UUID identifying each entity
Get comfortable with extId early. Almost every subsequent operation, updating a VM, attaching a disk, reading a task, etc., is addressed by extId rather than by name.
Use the SDKs where you can: Nutanix publishes official v4 SDKs for Python, Java, Go, and JavaScript, generated from the same OpenAPI definitions that document the REST endpoints.
The SDKs are worth using because they handle several things you would otherwise have to implement by hand, most notably the request identifier header required on write operations. Raw HTTP is still worth learning, because it is what you will fall back on when you are debugging, or working in an environment where installing an SDK is not an option.
Note that the SDKs are installed per namespace. A script that creates a VM on a chosen cluster and subnet will pull in the vmm, clustermgmt, and networking clients rather than one single package.
Common first-run problems
- 404 on a valid-looking path: usually the wrong namespace, or an API version your release does not expose
- 401 responses: check for a stray newline in the base64 encoding of the credentials
- TLS errors: expected against a default self-signed certificate
- Copied examples that fail: older articles reference Early Access paths such as v4.0.a1 or v4.0.b1, which are not the GA path
- Empty result sets: the account authenticated successfully but has no visibility of the entities, which is an authorization problem rather than an API problem
That last one is worth dwelling on. A 200 response with an empty list looks like a working script and an empty cluster. It is very often a permissions boundary instead.
Summary: The v4 APIs are consistent once you learn the pattern: endpoint, /api, namespace, version, resource. Start with a read-only list request, keep the result set small, and get familiar with extId because everything else depends on it.
Use basic authentication to prove connectivity, then move to a service account before anything becomes scheduled or shared. Writes behave differently from reads, and that is where the next posts in this series pick up.
Series Links:
- Part 1: Getting Started with the Nutanix v4 REST APIs
- Part 2: Nutanix API v3 vs v4: What Changed and How to Plan a Migration
- Part 3: Asynchronous Tasks and ETags: Making Safe Writes
- Part 4: Filtering, Pagination, and Projections
- Part 5: Securing Nutanix API Access: Service Accounts, Keys, Least Privilege
Official Resources
What Do You Think? Are you writing new automation directly against v4, or still maintaining v3 scripts that work well enough to leave alone?
