Skip to main content

API schema update — August 10, 2026

The root swagger.json was replaced with the latest export supplied by the backend team. The contract now identifies itself as ZennoHosting API rather than ZennoHosting API (DEV). The documented runtime base URL and the OAuth2 security flow are unchanged. Operation count went from 76 to 72.

Added endpoints​

  • Resource limits: GET /limits returns per-user quotas — projects, access tokens, networks, public IPs and the summed CPU, RAM and disk of all VMs — each with its limit, current usage and remainder.
  • Name-length limits: GET /limits/name-lengths returns the maximum lengths for project, network, VM, SSH key and access-token names, and for an SSH public key value. These are validation rules, not quotas.
  • VM state counts: GET /projects/{projectId}/vms/state-counts returns the number of VMs in a project broken down by lifecycle status and by power state, computed server-side.

A new Limits tag groups the two limits endpoints.

Removed endpoints​

  • Administrative saga endpoints under /admin/sagas — list, detail, finalize and force-compensate — announced in the July 14, 2026 update. Their generated reference pages, schemas and the saga-type, states and correlation-id parameter pages are gone with them.
  • Payment endpoints under /payments. They were already excluded from the documented surface by excludedTags, so nothing changes on the site.

Schema changes that affect clients​

  • New status field on VMs, networks and public IPs. The ResourceStatus enum — creating, active, updating, deleting, failed — is now the recommended way to display a resource's state. The existing operation/operationStatus pair is retained only for backward compatibility.
  • OperationResponse.lastError was replaced by failureCode, typed as the new OperationFailureCode enum: insufficientCapacity, timeout, internal.
  • New ApiProblemDetails type extends the problem-details body with a code member — a stable machine-readable identifier of the error condition. It is currently declared on one response only: the 409 from VM creation, where code is insufficientCapacity. Every other error response still uses the base type without code.
  • ConfigurationResponse gained availability and maxCount: advisory signals of whether the cluster can host the configuration right now.
  • RebuildVmRequest gained deleteBackups, defaulting to false.
  • BackupResponse gained sourceImageId, null for backups created before the field existed.
  • NetworkResponse, PublicIpResponse and VmResponse gained status.
  • ProjectResponse.vmCount is now marked deprecated in favour of resourceCounts.vms.
  • Ten new schemas: ApiProblemDetails, OperationFailureCode, ResourceLimitsResponse, ResourceNameLengthLimitsResponse, ResourceQuotaResponse, ResourceStatus, VmPowerStateCountsResponse, VmResourceLimitsResponse, VmStateCountsResponse, VmStatusCountsResponse. No schemas were removed.

Breaking changes and migration notes​

  • Clients reading lastError from an operation must switch to failureCode; the old field is gone, not deprecated.
  • Any tooling calling /admin/sagas will now get a 404. There is no replacement in this contract.
  • Clients displaying resource state should move from operation/operationStatus to status. Note that status is active after an operation failed but was handled normally — a start, stop, reboot or resize that can simply be retried leaves the resource active. Judge an operation's outcome from the operation record, not from the resource.
  • The global OAuth2 requirement is unchanged. Regenerate API types before upgrading.

Documentation follow-ups completed with this update​

  • New authored pages: Limits and quotas, API errors and Inventory and monitoring.
  • Statuses and lifecycle was rewritten around status and now carries the list of fields retained only for compatibility.
  • The guides picked up availability/maxCount, sourceImageId and deleteBackups.
  • Generated operation labels are now short imperative titles instead of full sentences, and internal .NET type names no longer leak into public descriptions.

Known gaps in the contract​

Reported to the backend team, documented here as-is:

  • Enum casing is inconsistent: ResourceStatus and OperationFailureCode are lower camel case (creating, internal), while ApiOperationStatus, VmBootStatus and ResourceOperation are Pascal case (Queued, Running, Provision).
  • The OperationFailureCode description refers to a fallback value Internal, which does not exist in the enum; the actual value is internal.
  • ApiProblemDetails is wired to a single response, so code cannot yet be relied on across the API.
  • GET .../vms/{vmId}/metrics returns deterministic mock data, and POST .../vms/{vmId}/resize always answers 503 Service Unavailable. Both remain in the reference but are excluded from the authored guides.