Fleet Control API: schemas
The request and response bodies of the operations in this API.
AddCustomerDeploymentDto
AddCustomerDistributionDto
| Property | Type | Required | Description |
|---|
distributionId | string | yes | |
ref | string or null | no | |
repo | string or null | no | |
AddCustomerRepoDto
| Property | Type | Required | Description |
|---|
kind | CustomerRepoKind | yes | |
ref | string or null | no | |
url | string | yes | |
AddModelDto
| Property | Type | Required | Description |
|---|
config | object or null | no | Engine-specific extra config (vLLM args, Ollama params). |
engine | ModelEngine | yes | |
gpuMemFraction | number or null | no | vLLM gpu_memory_utilization (0–1). REQUIRED for vLLM and capped at 0.9 — an unbounded value would OOM the platform on unified memory. |
isDefault | boolean | no | |
maxContext | number or null | no | |
modelRef | string | yes | HF repo id for vLLM, Ollama tag for Ollama. |
profileId | string | yes | |
quantization | string or null | no | |
source | ModelSource | yes | |
ApplianceConfigDto
| Property | Type | Required | Description |
|---|
applianceId | string | yes | |
config | object | yes | |
ApplianceConfigDtoDataEnvelope
ApplianceDto
| Property | Type | Required | Description |
|---|
clientId | string | yes | |
createdAt | string (date-time) | yes | |
dgxOsVersion | string or null | no | |
hardwareSerial | string or null | no | |
id | string | yes | |
name | string | yes | |
profileId | string or null | no | |
status | ApplianceStatus | yes | |
updatedAt | string (date-time) | yes | |
ApplianceDtoDataArrayEnvelope
ApplianceDtoDataEnvelope
ApplianceProfileKind
Type: one of "lean-dgx", "standard-dgx", "airgap-dgx", "full-cloud"
ApplianceStatus
Type: one of "registered", "provisioning", "active", "retired"
ClientBrandingDto
| Property | Type | Required | Description |
|---|
clientId | string | yes | |
configured | boolean | yes | Whether this customer states ANY product identity. false is the resting state and NOT an error: the installation renders as Xema, which is the correct default. A 200 rather than a 404 so a console can say "nobody has branded this customer" instead of treating the resting state as an exception. |
description | string | no | The search-result and link-preview description (~165 chars). |
faviconUrl | string | no | A favicon URL. Same shape rule as logoUrl. |
legalName | string | no | The legal entity named in the copyright line. |
logoUrl | string | no | A logo image URL. An http(s) URL, or a root-relative path — which is the only shape an air-gapped box can serve. |
productName | string | no | The product name, as it is written everywhere. |
supportUrl | string | no | A support destination. Absent means NO support link is rendered anywhere — the host does not invent one. |
tagline | string | no | The positioning line. Short enough for a footer column. |
updatedAt | string (date-time) or null | no | |
ClientBrandingDtoDataEnvelope
ClientDto
| Property | Type | Required | Description |
|---|
createdAt | string (date-time) | yes | |
id | string | yes | |
name | string | yes | |
slug | string | yes | |
subscriberOrgId | string or null | yes | SUBJECT reference, never an authorization scope: the Xema org this customer OPERATES AS, when the customer is also a tenant of this platform. The deterministic join key from a self-serve subscription to this customer record. null for a customer onboarded purely by an operator (an appliance buyer who is not a tenant here). Written only when the client is created (POST /clients, POST /clients/ensure) and never updated. |
updatedAt | string (date-time) | yes | |
ClientDtoDataArrayEnvelope
| Property | Type | Required | Description |
|---|
data | array of ClientDto | yes | |
ClientDtoDataEnvelope
| Property | Type | Required | Description |
|---|
data | ClientDto | yes | |
CreateClientDto
| Property | Type | Required | Description |
|---|
name | string | yes | |
slug | string | yes | URL-safe slug, unique across the fleet (lowercase a-z0-9-). |
subscriberOrgId | string | no | SUBJECT reference (never an authorization scope): the Xema org this customer OPERATES AS, when the customer is also a tenant of this platform. Optional here: an operator onboarding an appliance buyer who is not a tenant leaves it unset. The self-serve path does not use this route — it uses POST /clients/ensure, which is idempotent on this value. |
CreateCustomerDto
| Property | Type | Required | Description |
|---|
name | string | yes | |
slug | string | yes | URL-safe slug, unique across the fleet (lowercase a-z0-9-). |
status | CustomerStatus | no | |
CreateProvisioningProfileDto
| Property | Type | Required | Description |
|---|
clientId | string | yes | |
config | object | yes | Per-service Helm values overlay authored centrally. |
distributionId | string | no | Optional id of the distribution this profile derives its biome-set core from. |
distributionLock | object | no | Optional sealed distribution.lock.json (kernel DistributionLock, schemaVersion 5) produced by xema edition seal. Optional on a draft; REQUIRED to publish (a profile without one is refused with 409), and the enabled server-biome set is derived only from its biomes[] at materialize time. It is read at create with the reader materialize uses: an unsealed resolve preview, an unsupported schemaVersion or a malformed field is refused with 422 and nothing is stored. |
enabledBiomes | array of string | yes | Slugs of biomes selected for this setup. A recorded selection only: the deployable set comes from distributionLock, which publish requires. |
inferenceEngine | InferenceEngine | yes | |
name | string | yes | |
profileKind | ApplianceProfileKind | yes | |
slug | string | yes | URL-safe slug, unique within the client. |
targetClass | DeploymentTargetClass | yes | |
CustomerDeploymentDto
CustomerDeploymentDtoDataEnvelope
CustomerDeploymentOperator
Type: one of "xema", "customer"
CustomerDeploymentTarget
Type: one of "cloud", "customer-cloud", "marketplace-aws", "marketplace-azure", "appliance-dgx"
CustomerDetailDto
CustomerDetailDtoDataEnvelope
CustomerDistributionDto
| Property | Type | Required | Description |
|---|
createdAt | string (date-time) | yes | |
customerId | string | yes | |
distributionId | string | yes | |
id | string | yes | |
ref | string or null | no | |
repo | string or null | no | |
CustomerDistributionDtoDataEnvelope
CustomerDto
| Property | Type | Required | Description |
|---|
createdAt | string (date-time) | yes | |
id | string | yes | |
name | string | yes | |
slug | string | yes | |
status | CustomerStatus | yes | |
updatedAt | string (date-time) | yes | |
CustomerDtoDataEnvelope
CustomerImageDeliveryMode
Type: one of "shared", "mirror", "airgap"
CustomerImageEntitlementDto
| Property | Type | Required | Description |
|---|
createdAt | string (date-time) | yes | |
customerId | string | yes | |
distributionId | string | yes | |
id | string | yes | |
mode | CustomerImageDeliveryMode | yes | |
registryTarget | string | yes | |
CustomerImageEntitlementDtoDataEnvelope
CustomerRepoDto
| Property | Type | Required | Description |
|---|
createdAt | string (date-time) | yes | |
customerId | string | yes | |
id | string | yes | |
kind | CustomerRepoKind | yes | |
ref | string or null | no | |
url | string | yes | |
CustomerRepoDtoDataEnvelope
CustomerRepoKind
Type: one of "distribution", "biomes", "deploy"
CustomerStatus
Type: one of "prospect", "active", "suspended", "churned"
CustomerSummaryDto
| Property | Type | Required | Description |
|---|
applianceCount | number | no | Number of appliances registered for this customer. |
createdAt | string (date-time) | yes | |
deploymentCount | number | no | Number of deployments this customer runs. |
id | string | yes | |
name | string | yes | |
slug | string | yes | |
status | CustomerStatus | yes | |
updatedAt | string (date-time) | yes | |
CustomerSummaryDtoDataArrayEnvelope
DeploymentTargetClass
Type: one of "appliance-dgx", "customer-cloud", "marketplace-aws", "marketplace-azure"
EngineModelRenderDto
| Property | Type | Required | Description |
|---|
gpuMemFraction | number or null | yes | |
maxContext | number or null | yes | |
modelRef | string | yes | HF repo id (vLLM) or Ollama tag (Ollama) the engine pulls. |
quantization | string or null | yes | |
servedModelName | string | yes | Deterministic slug served by the engine (--served-model-name / the gateway modelSlug). |
source | ModelSource | yes | |
EngineRendersDto
GatewayProviderDescriptorDto
GatewayProviderDescriptorDtoDataEnvelope
GatewayProviderEntryDto
| Property | Type | Required | Description |
|---|
engine | ModelEngine | yes | |
isDefault | boolean | yes | |
modelRef | string | yes | |
recommendedBaseUrl | string | yes | In-cluster OpenAI-compatible base URL hint for this engine on the appliance. |
InferenceEngine
Type: one of "vllm", "ollama", "both", "none"
InferenceRenderDto
| Property | Type | Required | Description |
|---|
contentHash | string | yes | sha256 hex of the gateway+engines content — change detection for fetch-and-apply. |
engines | EngineRendersDto | yes | |
gateway | GatewayProviderDescriptorDto | yes | |
profileId | string | yes | |
renderedAt | string (date-time) | yes | |
InferenceRenderDtoDataEnvelope
ModelActivationState
Type: one of "inactive", "active"
ModelConfigDto
| Property | Type | Required | Description |
|---|
activation | ModelActivationState | yes | |
config | object or null | no | |
createdAt | string (date-time) | yes | |
engine | ModelEngine | yes | |
gpuMemFraction | number or null | no | |
id | string | yes | |
isDefault | boolean | yes | |
maxContext | number or null | no | |
modelRef | string | yes | |
profileId | string | yes | |
quantization | string or null | no | |
source | ModelSource | yes | |
updatedAt | string (date-time) | yes | |
ModelConfigDtoDataArrayEnvelope
ModelConfigDtoDataEnvelope
ModelEngine
Type: one of "vllm", "ollama"
ModelSource
Type: one of "huggingface", "ollama_registry"
ProblemActionableBy
Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed.
Type: one of "user", "org-admin", "platform", "none"
ProblemDetailsDto
RFC 9457 problem document. The declared members are the reserved core; extension members are TOP-LEVEL and OPEN, owned by the refusing plane.
| Property | Type | Required | Description |
|---|
actionableBy | ProblemActionableBy | no | Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed. |
code | string | yes | SCREAMING_SNAKE_CASE. The machine-branchable refusal, and the value a policy rule, a retry predicate and a UI branch all name. |
detail | string | no | Human-readable and specific to THIS occurrence. |
errors | array of ProblemFieldIssueDto | no | Field-level issues, when the refusal is about the request body. |
instance | string | no | URI reference identifying the occurrence — a request path, a run, a row. |
params | map of string or number or boolean | no | Safe i18n interpolation values for the message keyed by code — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics. |
retry | ProblemRetry | no | What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known. |
status | number | yes | The HTTP status code, repeated in the body so a logged document is self-contained. |
title | string | yes | Short, human-readable, and STABLE for a given type. Never per-occurrence — that is detail. |
traceId | string | no | W3C trace-context trace-id, present when the caller sent a traceparent. Omitted rather than invented when it did not. |
type | string | yes | Absolute URI identifying the refusal TYPE. Derived one-to-one from code, so a caller may branch on either and can never be told two different things. Never about:blank. |
ProblemFieldIssueDto
| Property | Type | Required | Description |
|---|
code | string | no | SCREAMING_SNAKE_CASE code of THIS issue, for a frontend i18n key. Present when the issue was minted by a declared problem. |
detail | string | yes | Prose for logs and developers. A frontend localises from code + params instead. |
params | map of string or number or boolean | no | Safe i18n interpolation values for this issue's code. |
pointer | string | yes | RFC 6901 JSON Pointer into the request body. Root is "/". |
ProblemRetry
What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known.
Type: one of "transient", "after-change", "never"
ProductIdentityFieldsDto
| Property | Type | Required | Description |
|---|
description | string | no | The search-result and link-preview description (~165 chars). |
faviconUrl | string | no | A favicon URL. Same shape rule as logoUrl. |
legalName | string | no | The legal entity named in the copyright line. |
logoUrl | string | no | A logo image URL. An http(s) URL, or a root-relative path — which is the only shape an air-gapped box can serve. |
productName | string | no | The product name, as it is written everywhere. |
supportUrl | string | no | A support destination. Absent means NO support link is rendered anywhere — the host does not invent one. |
tagline | string | no | The positioning line. Short enough for a footer column. |
ProvisioningArtifactDto
| Property | Type | Required | Description |
|---|
branding | ProductIdentityFieldsDto | no | The customer's PRODUCT IDENTITY, when they have registered one. OMITTED ENTIRELY when they have not — not {}, not seven empty strings. The appliance keys on the block's PRESENCE, so an unbranded customer's artifact is byte-identical to one produced before this field existed and xema-appliance provision does nothing rather than writing seven keys whose values are the host's own fallbacks spelled out. The seven fields become the XEMA_PRODUCT_* keys of the box's xema-host-web-runtime-config Secret, which the host-web chart already consumes with one envFrom.secretRef — so delivering a brand needs no chart change and no new channel. |
clientId | string | yes | |
clientSlug | string | yes | |
deploymentName | string | yes | Deployment/release name on the box. |
enabledBiomes | array of string | yes | |
inferenceEngine | InferenceEngine | yes | |
models | array of ProvisioningArtifactModelDto | yes | |
profileId | string | yes | |
profileKind | ApplianceProfileKind | yes | |
profileVersion | number | yes | |
targetClass | DeploymentTargetClass | yes | |
values | object | yes | |
ProvisioningArtifactDtoDataEnvelope
ProvisioningArtifactModelDto
| Property | Type | Required | Description |
|---|
engine | ModelEngine | yes | |
gpuMemFraction | number or null | no | |
isDefault | boolean | yes | |
maxContext | number or null | no | |
modelRef | string | yes | |
quantization | string or null | no | |
source | ModelSource | yes | |
ProvisioningProfileDto
| Property | Type | Required | Description |
|---|
clientId | string | yes | |
config | object | yes | |
createdAt | string (date-time) | yes | |
distributionId | string or null | no | |
distributionLock | object or null | no | |
enabledBiomes | array of string | yes | |
id | string | yes | |
inferenceEngine | InferenceEngine | yes | |
name | string | yes | |
profileKind | ApplianceProfileKind | yes | |
slug | string | yes | |
status | ProvisioningProfileStatus | yes | |
targetClass | DeploymentTargetClass | yes | |
updatedAt | string (date-time) | yes | |
version | number | yes | |
ProvisioningProfileDtoDataArrayEnvelope
ProvisioningProfileDtoDataEnvelope
ProvisioningProfileStatus
Type: one of "draft", "published", "archived"
RegisterApplianceDto
| Property | Type | Required | Description |
|---|
clientId | string | yes | |
dgxOsVersion | string or null | no | |
hardwareSerial | string or null | no | |
name | string | yes | |
profileId | string or null | no | Provisioning profile this appliance is built from. |
SetApplianceConfigDto
| Property | Type | Required | Description |
|---|
config | object | yes | Per-appliance config overrides, layered over the profile. |
SetClientBrandingDto
| Property | Type | Required | Description |
|---|
description | string | no | The search-result and link-preview description (~165 chars). |
faviconUrl | string | no | A favicon URL. Same shape rule as logoUrl. |
legalName | string | no | The legal entity named in the copyright line. |
logoUrl | string | no | A logo image URL. An http(s) URL, or a root-relative path — which is the only shape an air-gapped box can serve. |
productName | string | no | The product name, as it is written everywhere. |
supportUrl | string | no | A support destination. Absent means NO support link is rendered anywhere — the host does not invent one. |
tagline | string | no | The positioning line. Short enough for a footer column. |
SetCustomerImageEntitlementDto
UpdateApplianceStatusDto
UpdateCustomerDto
UpdateModelActivationDto