1. Introduction

1.1 What PanAPI Is

PanAPI is the RESTful management API for VDURA storage infrastructure: tenants, users, volumes, nodes, hardware, StorageSets, subnets, and the S3 gateway. It is the single backend service both panctl (the command-line client) and the VDURA web UI (Vantage) talk to; neither is more authoritative than the other, and changes made through one are immediately visible through the other. See the PanCTL User Guide’s introduction for that CLI-side perspective.

All endpoints are namespaced under the base path /api/v1. The realm also serves an interactive Swagger UI at /docs and the raw machine-readable specification at /openapi.json; this guide is generated directly from that specification (captured at API version 12.0.0, on 2026-10-19), so its endpoint and schema reference stays exactly in sync with what the realm actually accepts. For the most current behavior of a realm you administer, /docs on that realm is always the ground truth.

1.2 Authentication Schemes

Every call needs an Authorization: Bearer <JWT> header, except POST /auth/login, POST /auth/refresh, and GET /api/v1/about (see Chapter 4). Two schemes can supply that header, and only one may be active on a given request. A request carrying both credentials is rejected with 401:

• PasswordLogin: sign in with a tenant user name and password. The user name carries the tenant it belongs to, <tenant-name>/<user>. Leave the prefix off for the platform tenant, so admin signs in as the platform administrator.
• BearerJWT: present a JWT access token directly, such as one returned by POST /auth/tenant-switch or a long-lived API token from POST /auth/tokens.

The full authentication endpoint reference, including tenant switching and API token issuance, is Chapter 3.

1.3 Request and Response Conventions

• Content types. Most request and response bodies are application/json. The two token endpoints (POST /auth/login, POST /auth/refresh) take application/x-www-form-urlencoded instead, matching the OAuth2 password-grant convention.
• Success responses. A successful call returns either a JSON body describing the result (with a 2xx status) or 204 No Content for actions and deletes that return nothing.
• Error responses. Every error response is a JSON object with a detail field: a plain string for most errors ({"detail": "Not authenticated"}), or, for 422 Validation Error, a list of per-field ValidationError objects describing exactly which field failed and why. See Appendix A for the common error shapes shared across every endpoint in this guide. The endpoint sections below list the status codes their spec declares; the common codes apply to every endpoint whether or not they are listed.
• Tenant scoping. Most resources belong to a tenant. A tenant user’s calls are implicitly scoped to their own tenant; the platform tenant (Platform Admin) can typically pass an optional tenant_id query parameter or all_tenants on list endpoints to read across tenants. A tenant user’s writes stay in their own tenant, while a Platform Admin can write into any tenant through the /tenants/{tenant_id}/... paths.

1.4 Who May Call What

Access depends on the caller’s role, and some calls are open only to the platform tenant. The prose elsewhere in this guide follows the table below where the two differ.

Roles are defined per tenant, so an unknown role in a role-assignment request also returns 400. The S3 aggregator is off by default and must be turned on.

1.5 Common Procedures

These procedures must be run in the order shown. Run in another order, the steps fail with the status codes noted.

Onboard a tenant (Platform Admin):

1. PUT /api/v1/subnets/segment-type, once per realm, to choose VLAN or VXLAN. It must be set before the first subnet.
2. POST /api/v1/tenants to create the tenant.
3. PUT /api/v1/tenants/{tenant_id}/storagesets/{storageset_id} to give the tenant a StorageSet. Without it, creating a volume returns 404.
4. POST /api/v1/tenants/{tenant_id}/subnets to create the tenant’s subnet. Then wait until mount-info returns a non-empty rmlist. A non-empty directors list is not enough.
5. Create a tenant user and give it the admin role.
6. The tenant admin creates volumes. Always include hard_quota_bytes, with a value greater than 0.

Enable S3 (Platform Admin, then Tenant Admin):

1. PUT /api/v1/s3/enabled to enable S3 for the realm. Enabling the tenant before the realm returns 409.
2. PUT /api/v1/tenants/{tenant_id}/s3 to create the tenant’s S3 configuration.
3. PATCH /api/v1/tenants/{tenant_id}/s3 with enabled set to true and a default_prefix.
4. Create a gateway instance, which needs a subnet. A tenant gets at most one instance per node.
5. Start the instance. The call returns 202; poll the instance’s observed field until it reaches the desired state.
6. Create a bucket. Bucket calls return 503 until a gateway instance is running.

Delete a tenant (Platform Admin):

1. POST /api/v1/tenants/{tenant_id}/s3/instances/delete-all to remove the tenant’s S3 gateway instances.
2. Delete the tenant’s volumes.
3. Delete the tenant’s subnets.
4. DELETE /api/v1/tenants/{tenant_id}.

Any leftover resource, including an S3 gateway instance, makes the final call return 409.

1.6 How This Guide Is Organized

Chapter 2 is a single master index of every endpoint in the guide, for a full-text scan or search without opening each chapter in turn. Chapters 3 through 14 each cover one area of the API, grouped the same way the specification itself tags its endpoints: Authentication, Realm and Platform, Tenants, Tenant Users, PanFS Users, Service Accounts, Volumes, StorageSets, Subnets and Attachments, Nodes and Hardware, the S3 Gateway, and Observability. Each of those chapters opens with its own Endpoint Summary table (method, path, one-line summary) that doubles as that chapter’s index, followed by the full reference for every endpoint: parameters, request body fields, and response shapes. Appendix A covers the error conventions shared across all endpoints; Appendix B is an alphabetical index of every schema used anywhere in this guide.