Schemas

The hostname the organization is proving it controls, for example shop.acme.com. Normalized (lowercased, trailing root dot stripped) and validated server-side; see the domain's own normalize_domain.

The port the service listens on inside the container, 1 to 65535.

https only: the customer's own domains to serve on this endpoint. Each must be a domain the organization has verified, or a subdomain of one, exactly as for a Web App; certificates are issued automatically. All or nothing: one refused domain opens nothing. More can be added later.

port (the default, so a request written before kinds existed means what it always did), unit (a raw port per unit, see Add Service Endpoint) or https.

https only: the label of the free host (<label>.zone.<zone>.zaroz.cloud), one DNS label. Omitted, the host is named after the endpoint's id.

For port and unit: tcp, udp, or tcp_udp for one public number on both; required. For https: omit it (always TCP, TLS ends at the platform and the app serves plain HTTP); tcp is accepted.

The user to add to this organization.

Defaults to member, the least-privileged role: an omitted role must never widen access further than the caller asked for.

Files uploaded against this ticket that this message carries. Empty unless the caller uploaded something first; an attachment that is uploaded and never sent stays unreferenced and is not rendered anywhere.

fail (default) answers 409 no_warm_unit when no warm unit is ready; create cold-starts a new one already allocated to you (202).

Replaces the allocated unit's labels whole when given.

Replaces the allocated unit's user_data whole when given: the match's roster, map, mode.

true when if_none: create cold-started the unit: it is still starting.

true when this Idempotency-Key had already allocated the unit.

The unit, with its user_data and allocation (delivered_at is null until its agent has the files).

normal, pressure, or attack. Never unknown: an allocation whose state was not reported is absent from the list instead, so a caller can tell "not reported" from "reported as normal".

One step's answers as a RESPONSE (GET .../setup/steps, PUT .../setup/steps/{step}'s own echo). Same tag shape as [SetupStepAnswersDto] for the three Minecraft steps, whose answers hold nothing secret and so render identically either direction; NEVER the same shape for [Self::ServerPasswords], which reports only which ids are set, never a value or a ciphertext -- see [ServerPasswordsResponseDto].

What landing this answer cost the running service. live when the submitted answers matched what was already stored.

Whether provisioning is still waiting on at least one declared step after this write.

True when this answer completed the product's declared steps and (re)provisioning was started, but the attempt itself failed. The answer is still saved; a later read or retry can still succeed.

The closed vocabulary of setup steps kernel knows how to ask, validate and render. Adding a member is a reviewed code change here, in the dashboard's step registry, and in whichever product template starts reading its variables -- the same "closed set, matched code change" discipline [crate::domain::product_definitions::capabilities::CapabilityId] uses, for the same reason: a step nothing implements is a claim the platform cannot back.

Ord is derived so this can key a BTreeMap ([StepAnswersDocument::steps]): declaration order becomes iteration order there, which is incidental (the document is always looked up by key, never walked in order) but harmless.

Closed, policy-owned action catalog. Capabilities are exact: there is deliberately no prefix or glob matching, and unknown wire values are rejected during deserialization. PartialOrd/Ord exist so a capability set can be a BTreeSet, which is what [crate::domain::auth::application_token::ApplicationToken] stores. The ordering is the declaration order and is not a wire contract: nothing serializes it, and as_str remains the only stable representation.

Scope of one grant. Global means the capability is allowed regardless of resource. ResourceType is every resource in one namespace, while Resource names exactly one object.

"" when this product's params never asked for an email.

"" when this product's params never asked for a site title.

Mirrors [AppAdminApply] by hand.

Whether this product asks for an admin email at all.

Mirrors [UsernameRule] by hand.

None when this product does not ask for a site title at all.

Presentable name, the same one MyApplicationDelegationResponse carries.

The user's display name, as shown to other users.

The profile picture, addressed through /api/v2/assets/{id}. None when they never set one.

Set when the account was deleted. The profile is still answered so a listing can render "deleted user" rather than "unknown user".

At most [MAX_LOOKUP_IDS]; duplicates are fine.

The fully-qualified hostname, for example shop.acme.com.

Validated as a hostname before anything is persisted: trimmed, lowercased and stripped of a trailing dot, then refused if it is empty, longer than 253 characters, an IP address literal, a single label with no dot in it, or carries a label that is empty, longer than 63 characters, hyphen-terminated, or holds anything outside [a-z0-9-].

A domain the organization has verified, or a subdomain of one.

The UTC day, YYYY-MM-DD.

Absent when continuity cannot be stated honestly from our own measurements.

Absent while the episode is still open.

Arbitrary JSON.

User, Application, or System.

Which of the caller's services this entry is about (ZC-1277).

AdminAuditEntryResponse has always carried it, and its doc comment explains the omission here as these fields being "the scope of ITS request, not data about the entry". That is true of organization_id and was never true of this one: a customer read is scoped to an organization, and could narrow only as far as a project, so the service was never the scope of the request -- it was the one thing the customer could not learn.

Resolved through UserEmailService (checks oauth_accounts first, then password_credentials). None when neither source has an address for this user -- User itself carries no email field.

The label the customer gave it, or kernel's own timestamped default.

creating, ready, failed or restoring.

Present once the snapshot has finished or failed.

The step of an in-progress restore, or null when this backup is not currently being restored. One of stopping_workloads, detaching_pre, maint_attaching, reverting, detaching_post, csi_retaining_pv, csi_recreating_pvc, restarting_workloads.

When the current restore began, so a client can render "restoring for N minutes" without polling a second endpoint. null outside a restore.

Present once the snapshot has finished (status: "ready" or later).

The ceiling POST .../backups is refused against, published here so a panel never holds it as a literal.

read_only or read_write.

Bytes sent out of the bucket in the window (billed).

Hours with no measurement, filled with the nearest earlier one.

Hourly measurements, oldest first.

Average stored GiB over the whole window, as a decimal string.

What the data plane allows right now: open, read_only (over the cap), suspended (unpaid or moderated) or deleted. Suspended buckets keep their data and can still be browsed through the console.

Always path: use path-style addressing ({endpoint}/{bucket_name}/{key}); virtual-hosted style is not served.

The bucket name to use with that endpoint.

The S3 URL to point a client at.

The region name S3 clients sign with. Not a place: the bucket lives in region_id.

Where anonymous readers fetch objects ({url}{key}); absent unless public_read is on.

When the bucket's data will be purged, once deleted.

Latest measured stored bytes; absent before the first measurement (measured hourly).

The user's language, for example en-US.

The quote_id of a quote issued for this subscription.

When the subscription stops: the instant of this request.

One credit note per credited invoice.

pending_termination: the subscription now ends and the reaper tears the service down on its next tick.

The amount credited to the wallet, in minor units.

The caller's own session, spared when the change signs every other session out. Omit to be signed out everywhere, including here.

The customer's name for the service being bought.

The subscription is a purchase of a product and carries no name; this names the ServiceInstance the initial payment creates -- the VPS or container the customer actually refers to.

The URL segment addressing that service, unique within its project. Supplied rather than derived here: the console suggests one from the name as the customer types and lets them edit it.

The billing term to buy, in months: 1, 3, 6 or 12 (V-0717).

Omitting it buys the monthly term, which is what every client written before term choice sends. The plan's offered terms, with each one's price and saving, are its terms on the product plan listing. A term the plan is not sold at is refused (400), never sold monthly instead; the subscription renews at the same term and Price.

An optional discount code, exactly as the customer typed it.

A code that cannot be used is refused, not ignored: a customer who entered one and was charged full price anyway has been overcharged as far as they are concerned.

Public ports to open on the service once it runs. Omitting this (or sending none) buys exactly what every earlier request bought.

The customer names only the container port and the protocol(s); Zaroz assigns the public address and port. Each port is billed by the hour it is held, monthly in arrears: it is never part of the invoice this request creates, and the quote lists each one as a line of amount zero with the estimate in metered_estimate. A port that cannot be opened right after payment never fails the purchase: it is listed on the service as pending with the reason, and opened as soon as it can be. Refused for a product that offers none, past the plan's included ports when more are not priced, and above 10 per request.

The hardware tier inside region_id to run on, as RegionHardwareResponse.id from GET /api/v2/catalog/regions (decision-0347: a customer chooses between a region's tiers, each with its own Price). Omit it to let kernel place the service on the cheapest tier that fits. A tier that is not listed under region_id, or that the listing marks unavailable, is refused exactly as an unbuyable region is.

The operating system to install, for a VPS purchase (ProductFamily::VirtualMachine). Required for that family, and refused if sent for any other -- nothing else on /v2 installs an operating system. GET /api/v2/catalog/products/{id}/operating-systems lists what can be named here.

Which organization is buying, and therefore which one the subscription and its invoice bill to.

Optional, and omitting it means "my personal organization" -- the only thing /v2 checkout could bill before shared organizations became purchasable. Existing clients that send no organization_id keep the exact behaviour they had.

Sending one requires the caller to be entitled to spend that organization's money: an Owner or Admin membership, or its personal owner. A Member or Billing role is refused (403), never silently redirected to the caller's own organization. An organization the caller has no relationship to answers 404, the same as an unknown id, so ids cannot be enumerated by their refusal.

Which project the purchased service belongs to (§34.1's Organization -> Project -> Subscription -> Resource).

Optional, and omitting it means the buying organization's default project -- created on first use if it does not exist yet, the same resolution /v1 order creation has always applied for an organization with no project concept of its own. This is what makes checkout reachable without first showing the caller an organization: §11's invisibility on organization_id is worthless if project_id still forces one into view.

When supplied, it must name a project the buying organization owns; one belonging to another organization is refused rather than ignored, because a subscription filed under someone else's project misattributes that spend in every read that joins through it.

Where the service should run. Must be one of the regions GET /api/v2/console/catalog/regions returns for this product_id/plan_id: that read applies the same access and capacity rules checkout does, so anything it lists is buyable and anything it omits would be refused here.

Required for every purchasable product except a licence (ProductFamily::License), which is placed nowhere at all and is refused if this is sent. Omit it entirely for a licence purchase.

The size to buy, when the customer sized it themselves.

Omitting this buys the plan exactly as authored, which is what every existing client does and what every existing request means. This is an override, not a replacement: plan_id is still required and still decides which hardware profile runs the workload and which Price rates it, because those are placement and money rather than size.

A plan is one convenient point inside the range products.minimum_*/maximum_* describes, and a customer sizing their own instance is choosing a different point in the same range. Anything outside it is refused by Product::admits rather than clamped to fit: silently resizing somebody's order and then charging them for the result is the worse of the two answers.

This is also what makes persistent storage opt-in. A product whose minimum_storage_gb is zero admits a shape with no disk, that shape prices at zero against the storage rate, and the provisioner builds no volume for it.

Memory in GiB, fractional (0.5 = 512 MiB)

Storage in GiB. Zero buys no volume at all, where the product allows it.

The establishing invoice, in the same shape GET /billing/invoices/{id} already returns (InvoiceResponse) -- a client that just checked out pays this invoice through the existing invoice-id-keyed payment endpoints (POST /api/v1/invoices/{id}/checkout/mollie or .../paypal, both of which already resolve by InvoiceId alone).

ZC-1324 org trust S5 (§8.4). See [QuoteResponse::required_cents]'s own doc comment -- identical meaning, read AFTER this checkout's own effects (its reservation, if it wrote one) rather than before.

V-0449.04: postpaid disclosure, present only for the OWNER of an organization with a credit limit. See crate::contracts::standing::PostpaidDisclosureResponse.

The customer's name for the service they will receive.

The URL segment addressing it, unique within its project. Same rules as checkout's: 3-63 characters of lowercase letters, numbers and single hyphens.

The id from GET /api/v2/me/trials.

Which project to file it under. Omit for the personal organization's default project, created on first use. Must be omitted on POST /api/v2/me/trials/gaming, which always files into the games project.

Where to run it.

Ignored when the trial reports region_is_fixed, and omitting it otherwise means "anywhere that fits, cheapest first" -- resolved server-side, never by the client.

The zero-amount establishing invoice, in the same shape GET /billing/invoices/{id} returns. Already paid; it is returned so the customer's invoice list and this response cannot describe the same row differently.

How long the free period lasts, in hours, as declared.

The trial Price's id (decision-0353: a trial is a Price), to send back as trial_price_id to POST /api/v2/me/trials.

The plan this trial grants.

The product's display name, resolved server-side so a list needs no second request per row.

Whether this trial pins its own hardware or region. When true, any region_id sent to the claim is ignored, so a client must not offer a region picker for this row.

Why not, when claimable is false. A stable machine value plus a sentence; clients switch on code and never on message.

The region the trial runs in when it fixes one.

Always false on a fresh claim, and stated on the wire rather than assumed: this is the field that makes the trial free, and turning it on through PUT /api/v2/subscriptions/{id}/renewal is the whole of what converting a trial means. A client that hides it leaves the customer no way to keep their service.

active for a claim that provisioned, pending for the narrow window where the zero invoice settled but the row had not been re-read. Carried as the real status rather than a one-variant enum like CheckoutSubscriptionStatusResponse, because a claim -- unlike a checkout -- activates inside the same request.

When the free period stops. After this the subscription either starts billing (if the customer turned renewal on) or is suspended.

When the gateway stops accepting this ticket.

This is a redemption deadline, not a session deadline. cluster-agent checks exp once, when the socket is upgraded (gateway/edge_token.rs:41, called from gateway/terminal.rs:35); an attached session then runs until one side disconnects. So a client redeems the ticket immediately and never re-mints to stay connected: it mints again only to attach again.

The gateway URL to open a WebSocket against, carrying the signed ticket in its query string.

Binary frames both ways, and no subprotocol: cluster-agent's /terminal upgrade negotiates none (cluster-agent/src/gateway/mod.rs:88), unlike its /vnc and /ssh upgrades. Anything that is not a binary frame is dropped by the gateway rather than refused (gateway/terminal.rs:107), so there is no control channel to speak into.

Detail for the container's current state: the waiting reason's message while waiting, the terminated message while terminated, absent while running.

true only when this call made the unit.

The unit, with its user_data.

1 is an application error, 137 a SIGKILL and usually the OOM killer, 143 an ordinary SIGTERM.

Best-effort estimate of the next restart attempt. Kubernetes does not publish the kubelet's schedule, so this is reconstructed from the last termination plus the standard backoff.

Optional label. Kernel fills in a timestamped default ("Backup 2026-09-10 14:35") when this is absent, null, or blank.

read_only or read_write.

Display name. Blank or absent becomes "Key".

Storage cap in bytes, 1 GiB to 100 TiB. Absent takes 100 GiB. Above the cap the keys turn read-only until usage falls or the cap is raised.

Display name. Blank or absent becomes "Bucket".

Where the bucket lives. Defaults to the region of the subscription's price; when the price names a region this must match it.

1 to 64 characters, so the credential can be told apart when revoking it.

1 to 365; 90 when omitted.

Lower runs first. Ties are broken by the datapath, not here, so two rules sharing a priority have no defined order between them.

The source range this rule matches, IPv4 only and no broader than /8. Absent, null, or empty all mean "any source".

Defaults to true: a rule created disabled is almost always a mistake in the client rather than an intention, and /v1 defaults the same way.

Required for tcp and udp, refused for icmp and any. The domain enforces that (FirewallRule::create), so an omitted port on a TCP rule is a validation refusal rather than a rule that matches every port.

The grants the token holds. Every capability must be one the caller may grant themselves (GET /me/api-token-capabilities).

1-64 characters after trimming.

Must be true exactly when the authorization contains an admin-only capability, and then requires an elevated session.

Omit for a token that never expires on its own. Must be in the future.

Non-empty: a consent event that grants nothing is refused.

1-64 characters of letters, numbers, hyphens, or underscores. Lowercased and trimmed before it is checked for uniqueness -- see kernel_organizations::referral_link_service::normalize_slug.

Integer euro cents, and one of the fixed presets: 2500, 5000, 10000, 25000 or 100000. Any other amount is refused with invalid-field-value; top-ups are always EUR.

A provider a top-up can be started with. Mollie is deliberately absent: a Mollie top-up has no checkout and no settlement path in the kernel.

What the token may do, scoped to this organization. An empty list mints a token that authorizes nothing: for an organization credential, absence denies rather than permits.

Omit for a token that never expires on its own. Must be in the future.

Omitting this yields membership_tied, the safer shape: the token is revoked when the creator's membership of this organization ends. Pass organization_owned only when the credential is meant to outlive whoever set it up.

Distinct from OrganizationRoleResponse because request and response enums are separate types on /v2 (design doc §43.4), even where they currently carry the same variants.

URL-safe identifier, unique platform-wide (lowercase ascii letters, digits, and single internal hyphens).

URL-safe identifier, unique within the owning organization (lowercase ascii letters, digits, and single internal hyphens).

pull, push (pull and push) or admin (pull, push and delete).

Display name. Blank or absent becomes "Credential".

Spend cap in bytes of stored images, 1 GiB to 100 TiB. Absent takes 100 GiB. Above it pushes are refused until usage falls or the cap is raised; pulls and deletes keep working.

Display name. Blank or absent becomes "Registry".

Where the registry lives. Defaults to the region of the subscription's price; when the price names a region this must match it.

What each fire does (V-0702). Required: run_job for a cron-job service, tasks for any other.

Five space-separated fields. Syntax only is checked here and in the domain; computing the next fire time is the scheduler's job, out of scope for this slice.

The three concurrency policies a schedule may declare. Mirrors [OverlapPolicy] one for one; see this module's header for why it is not reused directly.

An IANA zone name, e.g. Europe/Helsinki. Checked syntactically only: this platform does not carry a timezone database yet, and adding one is a dependency decision for the owner, not this slice.

The person's email address. An address an account has verified is shared with that account at once, any other waits until an account verifies it and opens "Shared with me".

What the person may do, besides seeing the service: any of console, files, power, settings. Empty is allowed and means "may see it is up".

Non-empty: a delegation that grants nothing is refused.

mariadb or postgres; see GET .../shared-databases/engines for which are available right now.

The customer's own label. Blank or absent becomes "Database N".

Place it in this region. Strict when given: a region with no enabled host for engine is refused rather than silently placed elsewhere. Absent places it on the least-loaded host for engine.

One message in TicketDetailResponse::messages.

Soft-deleted messages never appear here at all -- this endpoint reads SupportMessageRepository::find_by_ticket_id_visible, which already excludes them, rather than /v1's find_by_ticket_id (every message, with the body blanked for a deleted one at render time). A /v2 read surface has no reason to reconstruct a "[deleted]" placeholder in the thread; see this crate's report.

A staff author's identity is never exposed: author_is_staff is true and author_name reads "Support Team". A non-staff message's author_name is that message's own author's display name, resolved per message by the caller of from_message -- not necessarily the caller of the request. A ticket's whole thread is now visible to every member of its organization (design doc §44.2), so a non-staff message may have been authored by the ticket's owner, another organization member, or the current caller; there is no single name that is correct for all of them.

One ticket visible to the caller, in the detail view (paired with its messages in TicketDetailResponse) -- any ticket belonging to any organization the caller may see (design doc §44.2), not only ones the caller personally opened. Same no-staff-identity rule as TicketSummaryResponse.

1 to 40 lowercase letters, digits or hyphens, starting and ending with a letter or digit. Never changes. u followed by digits, keys starting w- or zaroz, and the words the units routes use (allocate, events, policy, ...) are reserved.

At most 16 pairs; replaced whole. Absent means none for a new unit.

What the unit does when its process exits. Defaults to the policy's default_on_exit.

false creates the unit stopped: it holds no slot and costs nothing until it starts. Defaults to true.

Any JSON value up to 64 KiB, at most 32 levels deep. Not a secret store.

https:// and a public host; at most 2048 characters, no user name or password.

Event types to deliver (for example unit.ready); empty or absent for every type.

An external credential, without its secret.

zaroz_sp_.... Shown once: it is stored only as a digest and cannot be read back. Send it as Authorization: Bearer <token>.

The full credential, shown exactly once. Only a digest of its secret half is stored.

One of the caller's own personal API tokens (ZC-0512).

Never carries the secret, or even its digest. Only a digest of the secret half is stored on token_hash, and this response omits that field entirely: the full credential is returned exactly once, at creation (POST /me/api-tokens), and no later read -- this one included -- can reproduce it.

Unlike [crate::contracts::organization_api_tokens::OrganizationApiTokenResponse], capabilities here is not filtered to resource-scoped grants: a personal token may hold a global or resource-type-scoped grant as well as a resource-scoped one, so every capability the token's authorization names is reported, regardless of scope shape. A token created before restricted authorization existed carries no authorization at all (a legacy unrestricted token); it reports an empty list rather than "every capability there is", since there is no finite list of everything an unrestricted token can do to render here.

The full credential, shown exactly once. Only a digest of its secret half is stored, so no later request can return this value again.

One organization API token. Never carries the secret. The secret exists in exactly one response, [CreatedOrganizationApiTokenResponse], and only its digest is stored, so nothing can put it back here later.

The person who made the credential. null once that account is deleted.

Their display name, null when created_by is or the account cannot be read.

Minimal caller identity carried on a session payload.

Deliberately not the full /console/me shape (kernel_http_v2_identity::contracts::me::MeResponse): /v2 feature crates do not depend on one another (see crates/http/CLAUDE.md), so this is a small, independent projection sized for what a session response needs, not a shared type.

The oldest seq still kept.

Send this as after to read from the oldest kept event. Events before it were swept: re-read the unit list to resynchronise.

available, taken, invalid, platform_zone or not_verified. A string on the wire, like status above, so a new state does not break a generated client.

Normalized: lowercase, no trailing dot.

The id DELETE /service-instances/{id}/custom-domains/{route_id} names. It is the ingress resource's own id, so detaching addresses the exact row that was created rather than the hostname string, which a customer could otherwise re-send in a different case or with a trailing dot and miss.

pending, active or failed.

pending is not a synonym for broken. It is the ordinary state between accepting the name and cert-manager completing an HTTP-01 challenge, and that challenge cannot complete until the customer's own DNS points here -- so a client should render it as "waiting on your DNS", never as an error.

https://{hostname}, assembled here so every client renders the same link rather than each concatenating its own.

How many hostnames this service may hold at once, so a panel can disable its own add control instead of discovering the ceiling at a refusal.

The free platform hostname this service always answers on, or null when it publishes no HTTP ingress at all.

Also null when the instance's cluster could not be resolved, which is a different cause with the same rendering on purpose: the listing of attached domains is correct either way, and failing the whole read because a placement lookup faulted would blind a customer to the names they have already attached.

https://{platform_host}, present exactly when platform_host is. The shared wildcard certificate covers every platform host, so unlike a CustomDomainResponse.url this one is never waiting on a certificate to issue -- a client can render it as a ready link (copy and open-in-new-tab) the moment platform_host is non-null.

[DatabaseEngine] on the wire.

The database's own name on its server, which is the root a browser draws the tree under.

How full a database is.

Data plus index bytes, as the engine reports them. Cached for up to a minute and refreshed by any write through this API.

Set while the quota enforcement task has the database locked read-only for being over its quota.

The storage quota in bytes, or null for a database that has none (a dedicated database is sized by its own volume).

Arbitrary JSON.

Customer container registries. Registry products are not listed when false.

Domain Connect one-click DNS setup.

Transactional email. Without it no mail is ever sent (verification, password reset and notifications included).

Mollie card checkout for invoices.

NOWPayments crypto checkout.

Customer object-storage buckets. Bucket products are not listed when false.

PayPal checkout (wallet top-ups and invoice payment).

Stored unit log history. Live tail is unaffected.

Stored unit metrics history.

The Warden edge protection listener.

Web Push notifications.

Who started it, masked. A customer is named by their user id; an operator and the platform are deliberately anonymous.