API reference · API 1.0.0

Schemas

The 101 named schemas of the contract, in alphabetical order. A member that is not marked required may be absent; null appears only where the type says so. Within v1, answers may gain optional members and enums may gain values, so ignore members you do not know and treat an unknown value as unknown, not as an error.

Jump to a schema

AiGateway

object

The platform's AI gateway: one OpenAI-compatible endpoint in front of every served model, called with a virtual key.

NameTypeDescription
base_urlrequired string

The OpenAI-compatible base URL clients call (ends in /v1), with Authorization: Bearer <key>. From the same gateway credential the keys are minted against.

tiersrequired array of string

Every serving tier name in the catalogue, sorted.

Used by get/ai/gateway

AiModel

object

A model of the AI model catalogue: what it is (the metadata a client may set) and where its weights are (read-only, set by the store actions). A row exists whether or not any weights are present.

NameTypeDescription
architecture string | null

The model's architecture, as recorded: dense or moe (mixture of experts). Other values may appear.

benchmarks map of number (double) | integer | string | null

Published benchmark scores: benchmark name to score, e.g. {"SWE-bench Verified": 69.6}. As published by the vendor; not measured here.

category string | null

What the model is for: coding, agentic, reasoning, vision, embedding, rerank, general, speech or video. Other values may appear.

context_window string | null

The context window in human form, as recorded, e.g. 128K or 256K→1M.

created_atrequired string (date-time)

When the model entered the catalogue.

description string | null

A longer introduction, for the model's detail view.

dgx_reciperequired string | null

The serving recipe a DGX cluster runs it with, if any.

display_namerequired string

The name the catalogue shows. On create it defaults to the last part of repo.

frontier_equiv string | null

Which hosted frontier model it is roughly comparable to, and from when, in a few words. An estimate, not a measurement.

gatedrequired boolean

The Hugging Face repo needs an accept-click (access approval) before a pull.

gateway_tier string | null

The AI gateway serving tier the model is meant for, e.g. code or general (GET /ai/gateway/tiers). Recorded only: which model backs a tier is decided there, not here.

idrequired string

The model's id in the catalogue.

license string | null

The model's licence, as recorded, e.g. Apache-2.0, MIT.

locationrequired string | null

Read-only: set by the store actions (pull, node cache, purge), never by a client. Where the weights are. synology: the central model store; local: node caches only; both: the central model store and at least one node cache; null: nowhere yet. Other values may appear.

min_target string | null

The smallest hardware it runs on, in human form, e.g. 1× 3090 or 2×DGX.

model_card_url string | null

The model card's web address.

nas_pathrequired string | null

Where the central copy is; null without one.

nas_volumerequired string | null

Read-only: set by the store actions (pull, node cache, purge), never by a client. The central-store share holding the weights; null while there is no central copy.

node_cachesrequired array of NodeCacheRef

The node caches (see /node-caches).

notes string | null

Free-form notes of the platform's operators.

offline_readyrequired boolean

Read-only: set by the store actions (pull, node cache, purge), never by a client. A node holds a cached copy.

org string | null

The Hugging Face organisation the repo is published under. It may be a quantizer rather than the lab that built the model (that is vendor).

param_count_b number (double) | null

The parameter count in billions, as a number to sort by.

params string | null

The parameter count in human form, e.g. "480B (35B active)".

published string | null

When the model was released upstream, as recorded, e.g. 2024-11.

quant string | null

The weights' precision or quantisation, as recorded, e.g. BF16, FP8, AWQ, NVFP4.

reporequired string

A Hugging Face repo id org/name: each part starts with a letter or digit and holds only letters, digits, ., _ and - (no ..), at most 96 characters. Frozen after create.

serving_node string | null

Where the model is meant to be served: an AI node's hostname or a DGX cluster, as recorded. Recorded only: loading a model is not part of this API.

size_gb number (double) | null

The weights' size on disk in GB, as recorded.

statusrequired string

Read-only: set by the store actions (pull, node cache, purge), never by a client. planned (recorded, no weights yet), pulling (a copy into the central store is running), owned (the weights are in the central store) or serving (a node serves it). Other values may appear.

strong_axis string | null

What the model is strongest at, in a few words, e.g. agentic coding.

summary string | null

A one-line introduction, for a catalogue card.

updated_atrequired string (date-time)

The last change to the row, by a client or by a store action; equal to created_at until the first change.

vendor string | null

The lab that built the model. The Hugging Face organisation (org) may be a quantizer.

vendor_country string | null

The vendor's home country, as recorded, e.g. China, France, USA.

Used by post/ai-models, get/ai-models/{model_id}, patch/ai-models/{model_id}

Part of AiModelPage

AiModelCreate

object

A catalogue row. The model is created planned, with no central copy and no node cache: weights arrive only through the store actions, and pulling them is not part of v1. display_name defaults to the repo's last part.

NameTypeDescription
architecture string | null

The model's architecture, as recorded: dense or moe (mixture of experts). Other values may appear.

max length 40
benchmarks map of number (double) | integer | string | null

Published benchmark scores: benchmark name to score, e.g. {"SWE-bench Verified": 69.6}. As published by the vendor; not measured here.

category string | null

What the model is for: coding, agentic, reasoning, vision, embedding, rerank, general, speech or video. Other values may appear.

max length 24
context_window string | null

The context window in human form, as recorded, e.g. 128K or 256K→1M.

max length 20
description string | null

A longer introduction, for the model's detail view.

max length 20000
display_name string | null

The name the catalogue shows. On create it defaults to the last part of repo.

min length 1 · max length 255
frontier_equiv string | null

Which hosted frontier model it is roughly comparable to, and from when, in a few words. An estimate, not a measurement.

max length 120
gated boolean | null

The Hugging Face repo needs an accept-click (access approval) before a pull.

gateway_tier string | null

The AI gateway serving tier the model is meant for, e.g. code or general (GET /ai/gateway/tiers). Recorded only: which model backs a tier is decided there, not here.

max length 40
license string | null

The model's licence, as recorded, e.g. Apache-2.0, MIT.

max length 80
min_target string | null

The smallest hardware it runs on, in human form, e.g. 1× 3090 or 2×DGX.

max length 40
model_card_url string | null

The model card's web address.

max length 300
notes string | null

Free-form notes of the platform's operators.

max length 20000
org string | null

The Hugging Face organisation the repo is published under. It may be a quantizer rather than the lab that built the model (that is vendor).

max length 120
param_count_b number (double) | null

The parameter count in billions, as a number to sort by.

min 0 · max 9999999
params string | null

The parameter count in human form, e.g. "480B (35B active)".

max length 60
published string | null

When the model was released upstream, as recorded, e.g. 2024-11.

max length 20
quant string | null

The weights' precision or quantisation, as recorded, e.g. BF16, FP8, AWQ, NVFP4.

max length 40
reporequired string

A Hugging Face repo id org/name: each part starts with a letter or digit and holds only letters, digits, ., _ and - (no ..), at most 96 characters. Frozen after create; unique.

serving_node string | null

Where the model is meant to be served: an AI node's hostname or a DGX cluster, as recorded. Recorded only: loading a model is not part of this API.

max length 80
size_gb number (double) | null

The weights' size on disk in GB, as recorded.

min 0 · max 99999999
strong_axis string | null

What the model is strongest at, in a few words, e.g. agentic coding.

max length 40
summary string | null

A one-line introduction, for a catalogue card.

max length 2000
vendor string | null

The lab that built the model. The Hugging Face organisation (org) may be a quantizer.

max length 200
vendor_country string | null

The vendor's home country, as recorded, e.g. China, France, USA.

max length 40

Used by post/ai-models

AiModelPage

object

One page of AI models of the catalogue. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of AiModel

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/ai-models

AiModelPatch

object

JSON Merge Patch (RFC 7396): a member that is omitted keeps its current value; a member sent as null clears the field when the field is nullable (the schema marks it so), and null for any other field is a 422. A "" is a value (an empty string), not a clear. Of the metadata: display_name and gated are not nullable. repo is frozen and status, location, offline_ready, nas_volume are read-only: each may be sent with its current value and nothing else.

NameTypeDescription
architecture string | null

The model's architecture, as recorded: dense or moe (mixture of experts). Other values may appear.

max length 40
benchmarks map of number (double) | integer | string | null

Published benchmark scores: benchmark name to score, e.g. {"SWE-bench Verified": 69.6}. As published by the vendor; not measured here.

category string | null

What the model is for: coding, agentic, reasoning, vision, embedding, rerank, general, speech or video. Other values may appear.

max length 24
context_window string | null

The context window in human form, as recorded, e.g. 128K or 256K→1M.

max length 20
description string | null

A longer introduction, for the model's detail view.

max length 20000
display_name string | null

The name the catalogue shows. On create it defaults to the last part of repo.

min length 1 · max length 255
frontier_equiv string | null

Which hosted frontier model it is roughly comparable to, and from when, in a few words. An estimate, not a measurement.

max length 120
gated boolean | null

The Hugging Face repo needs an accept-click (access approval) before a pull.

gateway_tier string | null

The AI gateway serving tier the model is meant for, e.g. code or general (GET /ai/gateway/tiers). Recorded only: which model backs a tier is decided there, not here.

max length 40
license string | null

The model's licence, as recorded, e.g. Apache-2.0, MIT.

max length 80
location string | null

Read-only.

min_target string | null

The smallest hardware it runs on, in human form, e.g. 1× 3090 or 2×DGX.

max length 40
model_card_url string | null

The model card's web address.

max length 300
nas_volume string | null

Read-only.

notes string | null

Free-form notes of the platform's operators.

max length 20000
offline_ready boolean | null

Read-only.

org string | null

The Hugging Face organisation the repo is published under. It may be a quantizer rather than the lab that built the model (that is vendor).

max length 120
param_count_b number (double) | null

The parameter count in billions, as a number to sort by.

min 0 · max 9999999
params string | null

The parameter count in human form, e.g. "480B (35B active)".

max length 60
published string | null

When the model was released upstream, as recorded, e.g. 2024-11.

max length 20
quant string | null

The weights' precision or quantisation, as recorded, e.g. BF16, FP8, AWQ, NVFP4.

max length 40
repo string | null

Frozen.

serving_node string | null

Where the model is meant to be served: an AI node's hostname or a DGX cluster, as recorded. Recorded only: loading a model is not part of this API.

max length 80
size_gb number (double) | null

The weights' size on disk in GB, as recorded.

min 0 · max 99999999
status string | null

Read-only.

strong_axis string | null

What the model is strongest at, in a few words, e.g. agentic coding.

max length 40
summary string | null

A one-line introduction, for a catalogue card.

max length 2000
vendor string | null

The lab that built the model. The Hugging Face organisation (org) may be a quantizer.

max length 200
vendor_country string | null

The vendor's home country, as recorded, e.g. China, France, USA.

max length 40

Used by patch/ai-models/{model_id}

AiNode

object

One AI node. The ROSTER fields (from the portal's hardware inventory) are always present; the LIVE fields come from monitoring and are null when it cannot be read — this read never fails because of monitoring.

NameTypeDescription
cluster NodeCluster | null

Live (monitoring); null when monitoring_reachable is false.

collector_stale boolean | null

Live (monitoring); null when monitoring_reachable is false. The node's metrics collector has not reported for more than 30 seconds, so its model and GPU figures may be out of date.

cpu_util_pct number (double) | null

Live (monitoring); null when monitoring_reachable is false. CPU use over the last minute, 0-100.

disk_used_pct number (double) | null

Live (monitoring); null when monitoring_reachable is false. Root file system in use, 0-100.

gpu_class string | null

e.g. rtx-3090, gb10, rtx-pro-6000.

gpu_count integer | null

Live (monitoring); null when monitoring_reachable is false. GPUs reporting; also null when none does.

gpu_temp_max_c number (double) | null

Live (monitoring); null when monitoring_reachable is false. The hottest GPU's temperature, in °C.

gpu_util_avg_pct number (double) | null

Live (monitoring); null when monitoring_reachable is false. Average GPU use across the node's GPUs, 0-100.

hostnamerequired string

The node's hostname: its id here.

is_virtualrequired boolean

A GPU VM on a hybrid host (its power belongs to parent_host).

load1 number (double) | null

Live (monitoring); null when monitoring_reachable is false. The one-minute load average.

mem_used_pct number (double) | null

Live (monitoring); null when monitoring_reachable is false. Memory in use, 0-100.

mgmt_ip string | null

The node's management address, as the hardware inventory records it.

models array of NodeModel | null

Live (monitoring); null when monitoring_reachable is false. Loaded models.

monitoring_reachablerequired boolean

Monitoring reachable: false when monitoring could not be read, and every live field of this node is then null.

online boolean | null

Live (monitoring); null when monitoring_reachable is false.

parent_host string | null

For a virtual node, the host it runs on; null otherwise.

role string | null

Live (monitoring); null when monitoring_reachable is false. The node's role as monitoring labels it, e.g. ai-rtx, ai-epyc, ai-k8s; null when it carries none. Other values may appear.

services array of string

Other user-facing services the node hosts (they go offline with it): those seen answering, plus those the inventory declares.

site string | null

The site the node is at, as the hardware inventory records it.

specs_summary string | null

CPU, GPUs and memory in one line, from the hardware inventory.

status string | null

Live (monitoring); null when monitoring_reachable is false. serving, loaded_idle, idle, offline, standby or powered_off.

throttle_active boolean | null

Live (monitoring); null when monitoring_reachable is false. A GPU is throttling its clock (for power or heat).

uptime_seconds number (double) | null

Live (monitoring); null when monitoring_reachable is false. Seconds since the node booted.

vmid integer | null

For a virtual node, its VM id on parent_host; null otherwise.

vram_total_bytes number (double) | null

Live (monitoring); null when monitoring_reachable is false. GPU memory in total, in bytes, summed over the GPUs.

vram_used_bytes number (double) | null

Live (monitoring); null when monitoring_reachable is false. GPU memory in use, in bytes, summed over the GPUs (unified memory on gb10).

Used by get/ai/nodes/{hostname}

Part of AiNodePage

AiNodePage

object

One page of AI nodes. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of AiNode

This page's items, in the list's order.

monitoring_reachablerequired boolean

Monitoring reachable: false means every live field below is null.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/ai/nodes

ApiWarning

object

Something that did not go as planned, on a request that still succeeded — e.g. the customer was created but its GitLab group was not. A client must surface these (the provider reports them as diagnostics).

NameTypeDescription
coderequired string

The stable, machine-readable reason, e.g. gitlab_group_failed. Each operation names the warnings it can give.

messagerequired string

What happened, for a person. The wording may change.

Part of Customer,GatewayKey,LicenceInstalled,Project,ProjectUpdated,RoleGrant,ServingTier,User

AuditEvent

object

One change: who made it, what it touched, how they signed in and from where.

NameTypeDescription
actionrequired string

What was done, e.g. user.create, api_v1.post.

actorrequired string

Who made the change: the person's e-mail address as it was at the time, or system, pipeline:<run id>, ops:<script> for automated writers.

after_state any

The entity after the change as the writer recorded it: usually an object, null on a delete. Every member whose NAME looks secret (it contains secret, password, token, hash, pepper, credential, api_key and the like, at any depth) is always null here, whatever it held.

auth_kindrequired string | null

session, pat (personal API token) or service_account. Null when the writer did not record it: every row older than the public API, and today most portal pages and automated writers (only /api/v1, API-token management and platform settings record it).

before_state any

The entity before the change as the writer recorded it: usually an object, null on a create. Every member whose NAME looks secret (it contains secret, password, token, hash, pepper, credential, api_key and the like, at any depth) is always null here, whatever it held.

entity_idrequired string | null

Which one, as the writer spelled its id. For entity_type licence this is the licence serial, masked to its last group (ATAILA-XXXXX-XXXXX-XXXXX-XXXXX-5F8N5) unless the caller holds licence-admin-global, exactly as on GET /licence.

entity_typerequired string

The kind of thing changed, e.g. users, project.

idrequired string

The event's id: a string holding a positive integer. Ids grow with time but are not a clock; order by occurred_at.

occurred_atrequired string (date-time)

When the change was recorded.

request_idrequired string | null

The request's X-Request-ID, when recorded.

source_iprequired string | null

The client address as the portal saw it, when recorded.

token_idrequired string | null

The API token used, when auth_kind is pat or service_account.

Used by get/audit-events/{event_id}

Part of AuditEventPage

AuditEventPage

object

One page of audit events. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of AuditEvent

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/audit-events

Brand

object

The brand as stored. PUT /brand replaces every field of this object except the read-only first_party, attribution, version and updated_at: to change one field, send all of them back as read here.

NameTypeDescription
attributionrequired string

Read-only. The line printed under the product name; computed from first_party, never stored and never settable.

read-only
brand_colorrequired string

Six-digit hex colour; returned lower-case.

pattern ^#[0-9a-fA-F]{6}$
favicon_asset_idrequired string | null

A brand asset of kind favicon; null keeps the built-in one. In a PUT, null is a value that CLEARS the favicon, not "leave as is".

first_partyrequired boolean

Read-only. True only on ATAILA's own portal; selects the attribution line. No request can change it.

read-only
logo_asset_idrequired string | null

A brand asset of kind logo; null shows the built-in logo. In a PUT, null is a value that CLEARS the logo, not "leave as is".

logo_offset_xrequired integer

Horizontal nudge of the logo, in pixels.

min -40 · max 40
logo_sizerequired string

The sidebar logo size preset.

one of compact, medium, regular, large
page_titlerequired string

The browser-tab title.

min length 1 · max length 60
product_namerequired string

The wordmark in the sidebar and on the sign-in page.

min length 2 · max length 32
product_name_accentrequired string

A part of product_name rendered in brand_color. Empty colours the whole name.

max length 32
updated_atrequired string (date-time)

When the brand was last changed.

versionrequired integer

Bumped by every change; send it back in If-Match.

Used by get/brand, put/brand

BrandAsset

object

An uploaded logo or favicon. An asset is addressed by its content: the same file uploaded twice is one asset.

NameTypeDescription
bytesrequired integer

The file's size in bytes.

filenamerequired string

The file name given at upload, kept for display only; may be empty.

height integer | null

Height in pixels; null for an SVG.

idrequired string

The asset's id; logo_asset_id and favicon_asset_id name it.

kindrequired string

What the asset is for: a logo or a favicon.

one of logo, favicon
mimerequired string

The file's type, read from its bytes: image/png, image/webp or image/svg+xml for a logo; image/png, image/svg+xml or image/x-icon for a favicon.

sha256required string

The SHA-256 of the file's bytes, in lowercase hex.

uploaded_atrequired string (date-time)

When the file was first uploaded.

urlrequired string

Where the asset is served, without a file extension (/api/brand/assets/<sha256>); readable without signing in, like the sign-in page itself.

width integer | null

Width in pixels; null for an SVG.

Used by post/brand/assets, get/brand/assets/{asset_id}

Part of BrandAssetPage

BrandAssetPage

object

One page of brand assets. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of BrandAsset

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/brand/assets

BrandAssetUpload

object

The JSON form of an upload. Multipart (file + kind), as the portal screen sends, is accepted on the same operation.

NameTypeDescription
content_base64required string

The file, standard base64; at most 512 KB decoded. Its type is read from the bytes; no content type is sent.

min length 1 · max length 699058
filename string

The original file name, kept for display only: the asset is addressed by its content (sha256).

max length 200 · default ""
kindrequired string

What the asset is for: a logo or a favicon.

one of logo, favicon

Used by post/brand/assets

BrandPut

object

FULL REPLACEMENT of the v1 fields, never a partial update: every member is required. A member that is missing is refused with 422 validation_failed naming it in field (and in errors), so nothing is ever reset by omission; null for an asset id is a value and clears that asset. Send back every field of GET /brand, changed or not. Extra members — attribution and first_party among them — are refused with 422.

NameTypeDescription
brand_colorrequired string

Six-digit hex colour; returned lower-case.

pattern ^#[0-9a-fA-F]{6}$
favicon_asset_idrequired string | null

A brand asset of kind favicon; null keeps the built-in one. In a PUT, null is a value that CLEARS the favicon, not "leave as is".

logo_asset_idrequired string | null

A brand asset of kind logo; null shows the built-in logo. In a PUT, null is a value that CLEARS the logo, not "leave as is".

logo_offset_xrequired integer

Horizontal nudge of the logo, in pixels.

min -40 · max 40
logo_sizerequired string

The sidebar logo size preset.

one of compact, medium, regular, large
page_titlerequired string

The browser-tab title.

min length 1 · max length 60
product_namerequired string

The wordmark in the sidebar and on the sign-in page.

min length 2 · max length 32
product_name_accentrequired string

A part of product_name rendered in brand_color. Empty colours the whole name.

max length 32

Used by put/brand

CachedModelRef

object

A model with a complete copy on the node.

NameTypeDescription
cached_at string (date-time) | null

When the copy was last made or checked.

namerequired string

The model's display_name.

reporequired string

The model's Hugging Face repo id.

size_gb number (double) | null

The copy's size on the node's disk in GB, when measured.

Part of NodeStorage

ClusterMember

object

A node of a DGX cluster.

NameTypeDescription
crosslink_ip string | null

The member's address on the cluster's own interconnect (crosslink_subnet).

hostnamerequired string

The member's hostname.

mgmt_ip string | null

The member's management address.

role string | null

head or worker. Other values may appear.

Part of DgxCluster

ClusterServe

object

What a DGX cluster serves, as recorded when serving was started.

NameTypeDescription
model string | null

The model it serves.

recipe string | null

The serving recipe the cluster runs, by name.

served_at string (date-time) | null

When serving started, if recorded (a value that is not a timestamp reads as null).

Part of DgxCluster

Customer

object

A company on this platform. It owns tenants, and through them projects.

NameTypeDescription
billing_tierrequired string

INTERNAL: not invoiced (ATAILA's own and reference customers); PAYING: invoiced.

one of INTERNAL, PAYING
created_atrequired string (date-time)

When the customer was registered.

customer_indexrequired integer

The customer's number on this platform, 1-999; unique, archived customers included. Frozen.

default_email_tierrequired integer

The mail service the customer's mailboxes are created on by default: 1, 2 or 3, as the portal's customer page names them.

editionrequired string

sp (the default): a customer of this multi-tenant platform; enterprise: a customer with a single-tenant installation of its own. Frozen.

one of sp, enterprise
gitlab_grouprequired string

The customer's top-level GitLab group; also its primary tenant's slug. Frozen.

gitlab_status GitLabGroupStatus | null

Only with ?include=gitlab_status on a read; null when GitLab could not be asked (a warning then says why).

idrequired string

The customer's id.

long_namerequired string

The customer's full name.

notes string | null

Free text for operators, up to 2000 characters.

primary_contact_emailrequired string

An e-mail address. Stored and returned normalised: the domain is lower-cased (and internationalised domains are converted to their canonical form), the local part (before @) keeps its case exactly as sent, surrounding whitespace is dropped, and a Name <address> form is reduced to the address. Pat@Example.COM is therefore returned as Pat@example.com; compare with the domain case-folded to avoid a perpetual diff.

primary_contact_namerequired string

The name of the customer's primary contact.

primary_tenant_idrequired string

The tenant created with the customer; it can never be deleted.

short_namerequired string

Upper-case letters and digits, e.g. ACME; unique, archived customers included. Frozen.

statusrequired string

active, suspended or archived. archived is set only by DELETE /customers/{id} and is final: v1 has no way to restore an archived customer.

one of active, suspended, archived
warnings array of ApiWarning

What did not go as planned on this request, which still succeeded; empty when everything did. Show these to a person.

Used by post/customers, get/customers/{customer_id}, patch/customers/{customer_id}

Part of CustomerPage

CustomerCreate

object

A new customer. Its primary tenant (slug = gitlab_group) is created with it, and its GitLab group is created or adopted.

NameTypeDescription
billing_tier string

INTERNAL: not invoiced (ATAILA's own and reference customers); PAYING: invoiced. Default INTERNAL.

one of INTERNAL, PAYING · default "INTERNAL"
customer_index integer | null

Omit to have the server allocate the next free index.

min 1 · max 999
default_email_tier integer

The mail service the customer's mailboxes are created on by default: 1, 2 or 3, as the portal's customer page names them. Default 3.

one of 1, 2, 3 · default 3
edition string

sp (the default): a customer of this multi-tenant platform; enterprise: a customer with a single-tenant installation of its own. Frozen after create.

one of sp, enterprise · default "sp"
gitlab_grouprequired string

Also the primary tenant's slug, so the tenant slug rule applies: Lowercase letters, digits and '-', starting with a letter, 2-30 characters. Frozen after create.

pattern ^[a-z][a-z0-9-]{1,29}$
long_namerequired string

The customer's full name.

min length 3 · max length 80
notes string | null

Free text for operators, up to 2000 characters.

max length 2000
primary_contact_emailrequired string (email)

An e-mail address. Stored and returned normalised: the domain is lower-cased (and internationalised domains are converted to their canonical form), the local part (before @) keeps its case exactly as sent, surrounding whitespace is dropped, and a Name <address> form is reduced to the address. Pat@Example.COM is therefore returned as Pat@example.com; compare with the domain case-folded to avoid a perpetual diff.

primary_contact_namerequired string

The name of the customer's primary contact.

min length 2 · max length 80
short_namerequired string

Upper-case letters and digits, starting with a letter, 2-16 characters (e.g. ACME). Frozen after create.

min length 2 · max length 16 · pattern ^[A-Z][A-Z0-9]{1,15}$
status string

active (default) or suspended.

one of active, suspended · default "active"

Used by post/customers

CustomerPage

object

One page of customers. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of Customer

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/customers

CustomerPatch

object

JSON Merge Patch (RFC 7396): a member that is omitted keeps its current value; a member sent as null clears the field when the field is nullable (the schema marks it so), and null for any other field is a 422. A "" is a value (an empty string), not a clear. Only notes is nullable. archived is not a settable status: archiving is DELETE /customers/{id}.

NameTypeDescription
billing_tier string | null

INTERNAL: not invoiced (ATAILA's own and reference customers); PAYING: invoiced.

one of INTERNAL, PAYING
customer_index integer | null

Frozen.

default_email_tier integer | null

The mail service the customer's mailboxes are created on by default: 1, 2 or 3, as the portal's customer page names them.

one of 1, 2, 3
edition string | null

Frozen.

one of sp, enterprise
gitlab_group string | null

Frozen.

long_name string | null

The customer's full name.

min length 3 · max length 80
notes string | null

Free text for operators, up to 2000 characters. null clears it.

max length 2000
primary_contact_email string (email) | null

An e-mail address. Stored and returned normalised: the domain is lower-cased (and internationalised domains are converted to their canonical form), the local part (before @) keeps its case exactly as sent, surrounding whitespace is dropped, and a Name <address> form is reduced to the address. Pat@Example.COM is therefore returned as Pat@example.com; compare with the domain case-folded to avoid a perpetual diff.

primary_contact_name string | null

The name of the customer's primary contact.

min length 2 · max length 80
short_name string | null

Frozen.

status string | null

active or suspended; archiving is DELETE /customers/{id}.

one of active, suspended

Used by patch/customers/{customer_id}

DgxCluster

object

DGX nodes joined into one serving pool, as recorded. A DGX in no cluster serves on its own.

NameTypeDescription
created_atrequired string (date-time)

When the cluster was defined.

crosslink_subnet string | null

The subnet (CIDR) of the members' interconnect addresses.

error_message string | null

Why the last change failed, when status is error.

idrequired string

The cluster's id.

interconnectrequired string

The interconnect the members share: direct-cable, or the switch they are connected through. Other values may appear.

membersrequired array of ClusterMember

The member nodes, head first.

namerequired string

The cluster's name, unique; a load target names it so.

notes string | null

Free-form notes of the platform's operators.

serve ClusterServe | null

What the cluster serves; null when nothing is recorded.

statusrequired string

As recorded: defined, forming, active, breaking or error. This read does not converge a cluster that is mid-change (the portal's DGX page does).

topologyrequired string

How the members are wired: pair-direct (two nodes, cabled to each other), pair-switch (two nodes through a switch), ring3 (three nodes in a ring) or quad-switch (four nodes through a switch). Other values may appear.

updated_atrequired string (date-time)

The last change; equal to created_at until the first change.

Part of DgxClusterPage

DgxClusterPage

object

One page of DGX clusters. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of DgxCluster

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/ai/clusters

GatewayKey

object

An AI gateway virtual key: what one application of one tenant calls the gateway with, the tiers it may call and its limits. The key's value is never returned after the request that made it (secret).

NameTypeDescription
apprequired string

Frozen.

budget_duration string | null

The soft budget's period, e.g. 30d.

created_atrequired string (date-time)

When the key was created or adopted.

created_by string | null

The id of the user (a person or a service account) who created or adopted the key; null when not recorded.

envrequired string

Frozen.

one of dev, uat, prod
feature string | null

Frozen.

idrequired string

The key's id (a UUID).

key_aliasrequired string

<organisation-slug>-<env>-<app>[-<feature>] for a key created here; an adopted key keeps the alias it had. Unique among live keys.

liverequired string

Where models and the limits in this answer come from. present: the gateway's live values (a GET of one key); missing: the gateway no longer has the key (the registry values are shown); not_read: the gateway was not read and the registry values are shown. A list answers not_read, and so does EVERY write (create, PATCH, rotation): after a write, live is not_read and spend_usd is null until the next GET of the key. Read the key again (GET) for its live values.

one of present, missing, not_read
modelsrequired array of string

Tier names the key may call. A SET of tier names from the serving-tier catalogue: order carries no meaning and a name given twice counts once. Written de-duplicated and sorted (to the registry and to the gateway) and always returned sorted, so the same set always reads back the same.

organization_idrequired string

The tenant (organisation) that owns the key. Frozen.

originrequired string

api: created here; adopted: an existing gateway key taken under management. An adopted key's value lives with its consumer, so it cannot be rotated here (409 key_adopted).

one of api, adopted
project_id string | null

A project of the tenant the key serves; null when it serves none in particular.

rotated_at string (date-time) | null

When the key's value was last replaced (a rotation); null when never.

rpm_limit integer | null

Requests per minute the gateway allows the key; null for no limit.

secret string | null

The key's value (sk-…). Present ONLY in the response to the create or rotation that produced it, and only when that request set expose_secret: true; null everywhere else, including an idempotent replay of that same request. The value is always stored in the platform's secrets store at secret_path; the API never returns it again.

secret_field string | null

The field of that secrets-store entry that holds the value. Null when secret_path is.

secret_path string | null

Where the value is stored: a path in the platform's secrets store. Null for an adopted key whose location was never recorded.

soft_budget_usd number (double) | null

SOFT budget in US dollars: the gateway alerts when it is reached and NEVER blocks. There is no hard limit in v1.

spend_usd number (double) | null

Spend the gateway has recorded for this key (shadow USD). Only in the answer to a GET of one key: null in a list, and null in the answer to every write (create, PATCH, rotation) until the next GET.

token_hash_prefix string | null

The first 12 characters of the AI gateway's SHA-256 of the key, to find it in the AI gateway's own records. Never the value.

tpm_limit integer | null

Tokens per minute the gateway allows the key; null for no limit.

updated_atrequired string (date-time)

The last change; equal to created_at until the first change.

warnings array of ApiWarning

What did not go as planned on this request, which still succeeded; empty when everything did. Show these to a person.

Used by post/ai/gateway/keys, get/ai/gateway/keys/{key_id}, patch/ai/gateway/keys/{key_id}, post/ai/gateway/keys/{key_id}/rotations

Part of GatewayKeyPage

GatewayKeyCreate

object

A new virtual key, made on the gateway and stored in the secrets store. Its alias is <organisation-slug>-<env>-<app>[-<feature>].

NameTypeDescription
apprequired string

The application the key is for: lowercase words joined by single hyphens, 1-40 characters. Part of key_alias. Frozen.

min length 1 · max length 40 · pattern ^[a-z0-9]+(-[a-z0-9]+)*$
budget_duration string | null

The soft budget's period: a number and s, m, h, d or mo, e.g. 30d; the spend counted against soft_budget_usd restarts after each period.

pattern ^[1-9][0-9]{0,3}(s|m|h|d|mo)$
envrequired string

The environment the key is for: dev, uat or prod. Frozen.

one of dev, uat, prod
expose_secret boolean

Return the key's value in THIS response (secret). It is stored in the secrets store either way and never returned again.

default false
feature string | null

Optional: the application's feature the key is for, same rule as app. Part of key_alias. Frozen.

min length 1 · max length 40 · pattern ^[a-z0-9]+(-[a-z0-9]+)*$
modelsrequired array of string

A SET of tier names from the serving-tier catalogue: order carries no meaning and a name given twice counts once. Written de-duplicated and sorted (to the registry and to the gateway) and always returned sorted, so the same set always reads back the same. A tier that exists but serves nothing right now is accepted with a tier_not_serving warning.

min items 1 · max items 50
organization_idrequired string

The owning tenant.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
project_id string | null

Optional: a project of that tenant the key serves.

pattern ^[1-9][0-9]{0,8}$
rpm_limit integer | null

Requests per minute the gateway allows the key; null for no limit.

min 1 · max 1000000000
soft_budget_usd number (double) | null

SOFT budget in US dollars: the gateway alerts when it is reached and NEVER blocks. There is no hard limit in v1.

greater than 0 · max 1000000000
tpm_limit integer | null

Tokens per minute the gateway allows the key; null for no limit.

min 1 · max 2000000000

Used by post/ai/gateway/keys

GatewayKeyPage

object

One page of AI gateway virtual keys. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of GatewayKey

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/ai/gateway/keys

GatewayKeyPatch

object

JSON Merge Patch (RFC 7396): a member that is omitted keeps its current value; a member sent as null clears the field when the field is nullable (the schema marks it so), and null for any other field is a 422. A "" is a value (an empty string), not a clear. Here null clears a limit, the soft budget, its duration or the project; models cannot be null. The key's value is never changed here (that is a rotation).

NameTypeDescription
app string | null

Frozen.

budget_duration string | null

null clears it.

pattern ^[1-9][0-9]{0,3}(s|m|h|d|mo)$
env string | null

Frozen.

one of dev, uat, prod
feature string | null

Frozen.

models array of string | null

A SET of tier names from the serving-tier catalogue: order carries no meaning and a name given twice counts once. Written de-duplicated and sorted (to the registry and to the gateway) and always returned sorted, so the same set always reads back the same.

min items 1 · max items 50
organization_id string | null

Frozen.

project_id string | null

null clears it.

pattern ^[1-9][0-9]{0,8}$
rpm_limit integer | null

null clears it.

min 1 · max 1000000000
soft_budget_usd number (double) | null

SOFT budget in US dollars: the gateway alerts when it is reached and NEVER blocks. There is no hard limit in v1. null clears it.

greater than 0 · max 1000000000
tpm_limit integer | null

null clears it.

min 1 · max 2000000000

Used by patch/ai/gateway/keys/{key_id}

GatewayKeyRotation

object

A rotation: the key gets a new value, the old one stops working, and everything else about the key stays. The body may be empty.

NameTypeDescription
expose_secret boolean

Return the NEW value in this response (secret). It is stored in the secrets store either way.

default false

Used by post/ai/gateway/keys/{key_id}/rotations

GitLabGroupStatus

object

The customer's top-level GitLab group as GitLab reports it right now.

NameTypeDescription
existsrequired boolean

The group exists in GitLab.

full_path string | null

The group's full path; null when it does not exist.

web_url string | null

The group's page in GitLab; null when it does not exist.

Part of Customer

GitLabRepository

object

A repository of the project, in the customer's GitLab group.

NameTypeDescription
kindrequired string

app or www. Other values may appear.

pathrequired string

<customer group>/<repository>.

primaryrequired boolean

The project's main repository.

Part of ProjectOutputs

KubernetesNamespace

object

A Kubernetes namespace of the project, one per environment (Kubernetes backend only).

NameTypeDescription
envrequired string

The environment, e.g. dev.

namespacerequired string

The namespace's name.

Part of ProjectOutputs

LaunchCatalogEntry

object

A launchable model on a node. Never the load or unload commands.

NameTypeDescription
enabledrequired boolean

The entry is offered for loading in the portal.

enginerequired string

The serving engine: vllm, ollama or spark-vllm (a DGX cluster). Other values may appear.

hostrequired string

The node (for a cluster: its head).

keyrequired string

The entry's stable key, unique.

labelrequired string

The name the portal shows for the entry.

modelrequired string

The model it loads, as the serving engine names it.

portrequired integer

The port the loaded model answers on.

Part of LaunchCatalogPage

LaunchCatalogPage

object

One page of launch catalogue entries. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of LaunchCatalogEntry

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/ai/catalog

Licence

object

This platform's licence: its state as the licence gate sees it, and what the installed licence document says.

NameTypeDescription
bound_fqdnrequired string | null

The name the installed licence is bound to. A licence bound to another name puts the portal in DOMAIN_MISMATCH.

bundlerequired string | null

SENSITIVE. The installed bundle as an acplic1. string, for a principal holding licence-admin-global; null for everyone else and when none is installed.

days_remainingrequired integer | null

Whole days until valid_until; negative in grace. Null without a term.

document_digestrequired string | null

sha256 (hex) of the installed licence document envelope — the document member of the bundle, as ASCII. The same value the issuer records for the document it signed. Null when none is installed.

fqdnrequired string | null

The name this portal answers on, as the licence engine derives it.

grace_days integer | null

Days of grace after valid_until before the licence locks (14 unless the document says otherwise); null when none is installed.

growth_allowedrequired boolean

The licence gate lets the estate grow (projects, AI, customers and tenants): false in the restricted and read-only states.

installed_atrequired string (date-time) | null

When the installed document was installed.

instance_idrequired string | null

This portal's instance id, which a licence document binds. Null until the portal first activates or imports a licence.

licence_class string | null

The kind of licence: evaluation, commercial, internal-sp or partner; null when none is installed. Other values may appear.

licence_epochrequired integer | null

The installed document's epoch; a bundle installs only when its epoch is higher (see PUT /licence/bundle).

licence_id string | null

The installed licence's id, as ATAILA issued it; null when none is installed. The audit row of an install names it.

modulesrequired array of string

Entitled modules; empty unless the state gives full function.

overlaysrequired array of string

Conditions shown next to the state, never a state of their own: clock_skew, over_deployed.

product_code string | null

The product the licence is for, as ATAILA issued it, e.g. enterprise or eval-internal; null when none is installed or the document names none. Other values may appear.

serialrequired string | null

The licence serial. Shown in full only to a principal holding licence-admin-global; everyone else gets it masked to its last group. Null when no licence is installed.

serial_maskedrequired boolean

True when serial is masked for this caller.

socketsrequired LicenceSockets

Sockets licensed and observed.

sp_mode_enabledrequired boolean

The licence gate lets the service-provider plane (customers and tenants) change: requires growth, the sp-mode module and a tenancy mode other than single.

staterequired string

The licence state. ACTIVE, EXPIRING and GRACE give full function; UNLICENSED, PENDING_ACTIVATION, INVALID and DOMAIN_MISMATCH refuse what would grow the platform (403 licence_restricted); LOCKED and REVOKED refuse every change except installing a licence (403 licence_locked).

one of UNLICENSED, PENDING_ACTIVATION, INVALID, DOMAIN_MISMATCH, ACTIVE, EXPIRING, GRACE, LOCKED, REVOKED
state_reasonrequired string

Why the licence is in this state; empty when ACTIVE.

tenancy_moderequired string | null

single or multi, as the licence states it (multi is the service-provider plane: customers and tenants). Other values may appear.

tier string | null

The product tier: standard, enterprise, enterprise-plus or service-provider; null when none is installed. Other values may appear.

valid_from string (date-time) | null

When the licence term starts; null without a term.

valid_until string (date-time) | null

When the licence term ends; null without a term. After it the licence runs in GRACE for grace_days, then LOCKED.

writes_allowedrequired boolean

The licence gate lets ordinary changes through: false only in the read-only states (LOCKED, REVOKED).

Used by get/licence

LicenceBundlePut

object

A licence bundle to install in place of the installed licence document.

NameTypeDescription
bundlerequired string

SENSITIVE. The acplic1. bundle ATAILA issued for this portal.

min length 1 · max length 65536

Used by put/licence/bundle

LicenceInstalled

object

PUT /licence/bundle — the licence as it is after the install.

NameTypeDescription
bound_fqdnrequired string | null

The name the installed licence is bound to. A licence bound to another name puts the portal in DOMAIN_MISMATCH.

bundlerequired string | null

SENSITIVE. The installed bundle as an acplic1. string, for a principal holding licence-admin-global; null for everyone else and when none is installed.

days_remainingrequired integer | null

Whole days until valid_until; negative in grace. Null without a term.

document_digestrequired string | null

sha256 (hex) of the installed licence document envelope — the document member of the bundle, as ASCII. The same value the issuer records for the document it signed. Null when none is installed.

fqdnrequired string | null

The name this portal answers on, as the licence engine derives it.

grace_days integer | null

Days of grace after valid_until before the licence locks (14 unless the document says otherwise); null when none is installed.

growth_allowedrequired boolean

The licence gate lets the estate grow (projects, AI, customers and tenants): false in the restricted and read-only states.

installed true

Always true: the bundle was installed (a bundle that was not is a problem, never this answer).

default true
installed_atrequired string (date-time) | null

When the installed document was installed.

instance_idrequired string | null

This portal's instance id, which a licence document binds. Null until the portal first activates or imports a licence.

licence_class string | null

The kind of licence: evaluation, commercial, internal-sp or partner; null when none is installed. Other values may appear.

licence_epochrequired integer | null

The installed document's epoch; a bundle installs only when its epoch is higher (see PUT /licence/bundle).

licence_id string | null

The installed licence's id, as ATAILA issued it; null when none is installed. The audit row of an install names it.

modulesrequired array of string

Entitled modules; empty unless the state gives full function.

overlaysrequired array of string

Conditions shown next to the state, never a state of their own: clock_skew, over_deployed.

product_code string | null

The product the licence is for, as ATAILA issued it, e.g. enterprise or eval-internal; null when none is installed or the document names none. Other values may appear.

serialrequired string | null

The licence serial. Shown in full only to a principal holding licence-admin-global; everyone else gets it masked to its last group. Null when no licence is installed.

serial_maskedrequired boolean

True when serial is masked for this caller.

socketsrequired LicenceSockets

Sockets licensed and observed.

sp_mode_enabledrequired boolean

The licence gate lets the service-provider plane (customers and tenants) change: requires growth, the sp-mode module and a tenancy mode other than single.

staterequired string

The licence state. ACTIVE, EXPIRING and GRACE give full function; UNLICENSED, PENDING_ACTIVATION, INVALID and DOMAIN_MISMATCH refuse what would grow the platform (403 licence_restricted); LOCKED and REVOKED refuse every change except installing a licence (403 licence_locked).

one of UNLICENSED, PENDING_ACTIVATION, INVALID, DOMAIN_MISMATCH, ACTIVE, EXPIRING, GRACE, LOCKED, REVOKED
state_reasonrequired string

Why the licence is in this state; empty when ACTIVE.

tenancy_moderequired string | null

single or multi, as the licence states it (multi is the service-provider plane: customers and tenants). Other values may appear.

tier string | null

The product tier: standard, enterprise, enterprise-plus or service-provider; null when none is installed. Other values may appear.

valid_from string (date-time) | null

When the licence term starts; null without a term.

valid_until string (date-time) | null

When the licence term ends; null without a term. After it the licence runs in GRACE for grace_days, then LOCKED.

warnings array of ApiWarning

What did not go as planned on this request, which still succeeded; empty when everything did. Show these to a person.

writes_allowedrequired boolean

The licence gate lets ordinary changes through: false only in the read-only states (LOCKED, REVOKED).

Used by put/licence/bundle

LicenceSockets

object

CPU sockets: what the licence allows and what the census measured. over_deployed in overlays says the estate runs more than the licence allows.

NameTypeDescription
licensedrequired integer | null

Sockets the licence allows; null when uncapped or when no licence is installed.

observedrequired integer | null

Sockets the latest census measured; null when no census has run.

uncappedrequired boolean

The licence sets no socket limit.

Part of Licence,LicenceInstalled

LicenceSummary

object

The licence in short, as GET /meta reports it; GET /licence has all of it.

NameTypeDescription
days_remaining integer | null

Whole days until the licence term ends; negative in grace. Null without a term.

staterequired string

The licence state. ACTIVE, EXPIRING and GRACE give full function; UNLICENSED, PENDING_ACTIVATION, INVALID and DOMAIN_MISMATCH refuse what would grow the platform (403 licence_restricted); LOCKED and REVOKED refuse every change except installing a licence (403 licence_locked). Other values may appear.

state_reason string

Why the licence is in this state, for a person; empty when ACTIVE.

default ""

Part of Meta

LoadTarget

object

Somewhere a model can be served, with its VRAM budget: an AI node or a DGX cluster. Live figures when monitoring answers and the node is online, static fallbacks otherwise.

NameTypeDescription
engine string | null

The serving engine a load here uses: vllm (a node), k8s-vllm (a Kubernetes node) or spark-vllm (a DGX cluster). Other values may appear.

gpu_countrequired integer

GPUs: counted live when the node is online, estimated from its static budget otherwise; a cluster counts one per member.

hostnamerequired string

A node, or a DGX cluster by name.

is_cluster boolean

The target is a DGX cluster.

default false
loadablerequired boolean

False for fit-only targets (DGX clusters, Kubernetes nodes).

loaded_modelsrequired array of string | null

The served names of the models loaded here right now; empty when none is, or when monitoring cannot be read.

members array of string | null | null

A cluster's member hostnames, head first; null for a node.

onlinerequired boolean

The node (for a cluster: its head) is up, as monitoring sees it; false also when monitoring cannot be read.

per_gpu_gbrequired integer

VRAM per GPU in GB.

statusrequired string

As the AI node list reports it (serving, loaded_idle, idle, offline, standby, powered_off); for a DGX cluster active or forming while it is one. Other values may appear.

tensor_parallelrequired integer

How many GPUs one model is spread across when served here.

usable_vram_gbrequired number (double)

The weight budget in GB: the share of the serving GPUs' VRAM a model's weights may take, the rest being left for its working memory. A model fits when its size_gb is at most this.

vram_total_gbrequired integer

gpu_count times per_gpu_gb, in GB.

Part of LoadTargetPage

LoadTargetPage

object

One page of load targets. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of LoadTarget

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/ai-models/load-targets

Membership

object

A person's membership of a tenant, and their role in it.

NameTypeDescription
created_at string (date-time) | null

When the membership was created; null on a legacy row.

rolerequired string

developer can be read (legacy rows hold it) but not written: PUT accepts only owner, admin, member and viewer.

one of owner, admin, developer, member, viewer
tenant_idrequired string

The tenant.

user_idrequired string

The member.

Used by get/tenants/{tenant_id}/memberships/{user_id}, put/tenants/{tenant_id}/memberships/{user_id}

Part of MembershipPage

MembershipPage

object

One page of a tenant's memberships. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of Membership

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/tenants/{tenant_id}/memberships

Meta

object

What this API and this platform are. Read it before the first write: licence.state says whether writes will be refused, and dispatch_mode_effective whether provisioning can complete here.

NameTypeDescription
api_versionrequired string

This API's version, semantic versioning (1.0.0). Within 1.x the contract only ever grows.

dispatch_mode_effectiverequired string

What pipeline dispatch does on this platform, as /api/version reports it. live: work runs. dryrun: the dispatch is faked, nothing is executed, and provisioning or a release never completes. simulate: provisioning stages are marked done without running (simulate_stage_seconds each) and every other dispatch behaves as dryrun. Read it before booking work, to fail fast on a platform that will not carry it out.

one of live, dryrun, simulate
licencerequired LicenceSummary

The licence state in short.

modules array of string

The modules the licence entitles; empty unless the licence state gives full function.

default []
platform_versionrequired string

The platform build that answers, e.g. 1.0.181. Release notes and the developer documentation name contract changes by this version.

simulate_stage_secondsrequired number (double) | null

Under simulate: how long a simulated provisioning stage takes. Null in every other mode.

tenancy_mode string

single or multi, as the licence states it (multi is the service-provider plane: customers and tenants); empty without a licence.

default ""
tier string

The licence's product tier; empty without a licence.

default ""

Used by get/meta

NodeCache

object

A copy of a model's weights on one AI node's local disk: the fast, offline-ready serving copy, made from the central store by a cache run.

NameTypeDescription
idrequired string

<model id>:<node>.

model_idrequired string

The model (id of an AI model).

noderequired string

The AI node's hostname.

path string | null

Where the copy is on the node's disk, as the cache run reported it.

size_gb number (double) | null

The copy's size on the node's disk in GB, when measured.

staterequired string

cached once the copy is complete; pulling while it is made; absent or failed when a copy was removed or did not finish. Other values may appear.

updated_at string (date-time) | null

When the copy was last made or checked.

Used by get/ai-models/{model_id}/node-caches/{node}, put/ai-models/{model_id}/node-caches/{node}

Part of NodeCachePage

NodeCachePage

object

One page of a model's node caches. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of NodeCache

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/ai-models/{model_id}/node-caches

NodeCacheRef

object

A node that holds, or held, a copy of the model: the short form of a node cache (GET /ai-models/{id}/node-caches/{node} has the rest).

NameTypeDescription
noderequired string

The AI node's hostname.

size_gb number (double) | null

The copy's size on the node's disk in GB, when measured.

staterequired string

cached once the copy is complete; pulling while it is made; absent or failed when a copy was removed or did not finish. Other values may appear.

Part of AiModel

NodeCluster

object

The DGX cluster a node is a member of, as monitoring reports it.

NameTypeDescription
namerequired string

The cluster's name (name of a DGX cluster).

rolerequired string

The node's role in it: head or worker. Other values may appear.

Part of AiNode

NodeModel

object

A model loaded on a node right now, as monitoring reports it.

NameTypeDescription
cluster string | null

The DGX cluster serving it, when it is served by a cluster rather than by this node alone.

engine string | null

The serving engine, e.g. vllm or ollama. Other values may appear.

max_model_len integer | null

The longest context, in tokens, it is served with, when reported.

modelrequired string

The model as the serving engine names it (its repo or path).

port integer | null

The serving port (a node can run several).

served_name string | null

The name clients call it by on the node's OpenAI-compatible endpoint; null when not reported.

tensor_parallel integer | null

How many GPUs the model is spread across, when reported.

tiers array of string

Serving tiers it backs right now.

Part of AiNode

NodeStorage

object

A node's local disk as last scanned, with the models cached on it.

NameTypeDescription
cached array of CachedModelRef

The models with a complete copy on this node, largest first.

captured_at string (date-time) | null

When it was last scanned; null when never.

free_gb number (double) | null

Free space in GB, as last scanned.

kind string | null

The kind of disk, as the scan reported it: nvme, hdd or raid. Other values may appear.

mount string | null

Where the storage is mounted, as the scan reported it.

namerequired string

The share's name, or the node's hostname.

total_gb number (double) | null

Total capacity in GB, as last scanned.

Part of Storage

Operation

object

Long-running work: answered with 202 and a Location, then polled at GET /operations/{id} until status is succeeded or failed.

NameTypeDescription
created_at string (date-time) | null

When the work was booked.

dispatch_mode string | null

For work that dispatches pipelines: dryrun means this platform fakes the dispatch, nothing is executed, and the operation can never succeed; simulate means stages are marked done without running (see simulated).

one of live, dryrun, simulate
error object | null

When status is failed: code says why (stage_failed with the stage, release_failed, rejected, operation_timed_out, run_failed, run_timeout, ...), and message (detail for a model store run) says it for a person. Null otherwise.

idrequired string

<kind>:<native id>, e.g. provision:4711. The Location of the 202 that started it is /api/v1/operations/<id>.

kindrequired string

What the work is: provision (project provisioning), release (a release promotion), model-store-run (a model node cache or uncache, or a store run started in the portal) or order (a tenant order, placed in the portal; this API can poll one but not create it). Other kinds may appear.

message string | null

What is happening or what happened, for a person. The wording may change.

partial boolean | null

For tenant orders (order:<id>, placed in the portal: this API can poll an order but not create one): true when the order succeeded only in part — what was delivered does not fully match what was ordered; message says what is missing.

pipeline_url string | null

For release operations: the pipeline carrying the work out, once one is known.

resource_id string | null

That thing's id (<model id>:<node> for a node cache).

resource_type string | null

What the work is about: project, release_operation, ai_model, ai_model_node_cache, ai_node or order. Other values may appear.

simulated boolean | null

For project provisioning: the result rests on SIMULATED stages (dispatch_mode simulate). A succeeded simulated operation provisioned nothing.

stage string | null

For work done in stages (project provisioning): the stage it is on, or the one it stopped at.

statusrequired string

pending, running, awaiting_approval (a person must approve it in the portal), awaiting_operator (a person must act in the portal), succeeded or failed. The last two are final.

one of pending, running, awaiting_approval, awaiting_operator, succeeded, failed
updated_at string (date-time) | null

When it last changed; the end, once it has ended.

Used by put/ai-models/{model_id}/node-caches/{node}, delete/ai-models/{model_id}/node-caches/{node}, get/operations/{operation_id}, post/projects/{project_id}/provisioning, post/projects/{project_id}/release-promotions

Orchestration

object

The orchestration walking the project's stages right now: one at a time, in dependency order. It is the operation provision:<id>.

NameTypeDescription
current_stage string | null

The stage it is on (a stage key); null between stages.

kindrequired string

apply-all: every stage not yet done; apply-pending: only the stale stages; delete-all: a teardown, started in the portal.

one of apply-all, apply-pending, delete-all
operation_idrequired string

provision:<id>: poll it at /operations/{id}.

stalerequired boolean

Its worker stopped heartbeating; it is resumed by the platform, not by a new start.

started_at string (date-time) | null

When it started.

statusrequired string

The operation's status, as GET /operations/{id} reports it.

one of pending, running, awaiting_approval, awaiting_operator, succeeded, failed
updated_at string (date-time) | null

Its last heartbeat or step.

Part of Provisioning

Permission

object

A fine-grained permission key the portal honours: one level of one feature, in one scope.

NameTypeDescription
categoryrequired string

The group the portal lists the key under, e.g. AI or Security.

descriptionrequired string

What holding the key allows, for a person.

featurerequired string

The feature the key is about, e.g. users.

grantablerequired boolean

May be granted to a person (PUT /users/{id}/roles/{key}). A key that is not grantable is still honoured for those who hold it.

keyrequired string

<feature>-<level>-<scope>, e.g. users-read-global: what a role grant, a token's scopes and a 403's required name.

labelrequired string

The key's name, for a person.

levelrequired string

read reads; admin also changes. An operation that reads accepts either.

one of read, admin
mintablerequired boolean

May be carried by an API token.

scoperequired string

global: the whole platform. tenant: limited to the holder's tenants where the feature enforces it; an API token carries global keys only.

one of global, tenant

Part of PermissionPage

PermissionPage

object

One page of the permission catalogue. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of Permission

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/permissions

Problem

object

An error, as RFC 9457 problem details (application/problem+json). Some codes add members of their own: errors and field (validation_failed), required (forbidden), state, state_reason, remedy, remedy_url and entitlement (the licence_* codes), blockers (a refused delete), current_version (version_mismatch) and operation_id (work that is already running). A client should ignore a member it does not know.

NameTypeDescription
coderequired string

The stable, machine-readable reason, e.g. customer_not_found. Each operation names its own codes in its responses; the codes every operation can answer are listed under Errors in the API description.

detail string | null

What went wrong this time, written for a person. The wording may change at any time: branch on code, never on detail.

instance string | null

The path of the request that failed.

request_id string | null

The request's id, the same as the X-Request-ID response header. Quote it when asking for support.

statusrequired integer

The HTTP status code of the response, repeated.

titlerequired string

The HTTP status phrase, e.g. Forbidden.

typerequired string

urn:ataila:api:problem:<code>: names the kind of problem, the same for every occurrence of a code. An identifier, not a link.

ProdLock

object

A project's PROD data lock. While it is set, no data copy may target PROD, so PROD stays the source of truth for its data. It does not block code promotion.

NameTypeDescription
lockedrequired boolean

The lock is set.

locked_at string (date-time) | null

When it was set; null while it is not.

locked_by string | null

Who set it (an e-mail address, as recorded); null while it is not set.

project_idrequired string

The project.

Used by get/projects/{project_id}/prod-lock, put/projects/{project_id}/prod-lock

ProdLockPut

object

The PROD data lock's new state. Setting the state it already has changes nothing.

NameTypeDescription
confirm_unlock string | null

Required to UNLOCK: the project's short name, exactly.

max length 64
lockedrequired boolean

true sets the lock; false releases it and needs confirm_unlock.

Used by put/projects/{project_id}/prod-lock

Project

object

A project: its settings, its identity (frozen once created) and outputs, the names its provisioning produces.

NameTypeDescription
allow_public_https_egress boolean

Kubernetes projects: allow egress to public HTTPS.

default false
api_exposure string

Who reaches the PROD API: INTERNAL_ONLY (default) or PUBLIC. The UAT and DEV APIs are never public.

one of INTERNAL_ONLY, PUBLIC · default "INTERNAL_ONLY"
app_gateway string

shared rides the environment's app gateway; dedicated gets its own.

one of shared, dedicated · default "shared"
created_atrequired string (date-time)

When the project was registered.

customer_idrequired string | null

The tenant's customer; null only for a tenant no customer owns.

deployment_backendrequired string

k8s (default): namespaces on the shared Kubernetes clusters; vm: virtual machines of its own. Frozen.

one of vm, k8s
description string | null

Free text, up to 2000 characters.

max length 2000
enable_ai boolean

An AI endpoint at ai.<primary_domain>. Also allows outbound HTTPS to the internet, as allow_public_https_egress does.

default false
enable_cache boolean

An in-memory key-value cache.

default false
enable_dr_db_replica boolean

A disaster-recovery replica of the PROD database.

default true
enable_dr_object_storage_mirror boolean

A disaster-recovery mirror of the PROD object storage.

default true
enable_fullstack_app boolean

An application: its front end at app.<primary_domain> and its API at api.<primary_domain>, in PROD, UAT and DEV.

default true
enable_iis boolean

IIS/.NET hosting. VM backend only.

default false
enable_mssql boolean

SQL Server. VM backend only.

default false
enable_nas_object_storage_replication boolean

Replication of the object storage to the central store: recorded, not acted on yet.

default false
enable_object_storage boolean

Object storage for the project; false provisions none (a database-only project).

default true
enable_static_site boolean

A web site at www.<primary_domain> (and uat.www., dev.www.), seeded from www_template.

default true
enable_uat_app_public boolean

Make the UAT front end (uat.app.) reachable from the internet, e.g. to share a preview. DEV is never public.

default false
enable_uat_www_public boolean

Make the UAT web site (uat.www.) reachable from the internet.

default false
enable_web_www boolean

The web site ships from its own <gitlab_repo_slug>-www repository. Provisioning does not read it: the web site, its repository and its stages follow enable_static_site alone. With false, the platform's security scans leave the web site out, and a project with no application drops out of the traffic views. Keep it true (the default) unless the web site is not built from that repository.

default true
frontend_exposure string

Who reaches the PROD front end: PUBLIC (the internet; default) or INTERNAL_ONLY.

one of INTERNAL_ONLY, PUBLIC · default "PUBLIC"
frontend_variant string

The front-end framework the application is generated with: react (default), angular, vue or nuxt4.

one of react, angular, vue, nuxt4 · default "react"
github_repo_url string | null

A GitHub repository URL, recorded in the project's manifest as its mirror.

github_user string | null

A GitHub user name, recorded with the project.

gitlab_repo_slugrequired string

The repository name in the customer's GitLab group. Frozen.

has_mobile boolean

The project has a mobile app. Its PROD API is then public whatever api_exposure says: the app calls it from the internet.

default false
idrequired string

The project's id.

import_existing_repo boolean

The GitLab repository already holds code: provisioning does not seed it from the template.

default false
is_selfrequired boolean

One of ATAILA's own platform projects: readable, never writable through v1.

long_namerequired string

The project's display name, 2-60 characters. Double quotes, apostrophes, backslashes and control characters are refused: the name is written into the project's generated files.

min length 2 · max length 60
mssql_edition string

The SQL Server edition PROD and UAT run, with enable_mssql: express (default; free), standard or enterprise (licensed through the platform operator).

one of express, standard, enterprise · default "express"
network_onlyrequired boolean

Only the network zone is registered: no application and no web site. Frozen.

outputs ProjectOutputs | null

What the project's compiled manifest names; null for a project registered without one.

primary_domainrequired string

The domain the project's sites are named under (www., app., api., ai.). Frozen.

prod_object_storage_disks_per_vm integer

Data disks per PROD object storage node.

one of 1, 2 · default 2
prod_object_storage_node_count integer

PROD object storage nodes. With enable_object_storage, nodes times prod_object_storage_disks_per_vm must be at least 4.

one of 2, 4 · default 2
project_indexrequired integer

The third octet of the project's networks; unique on the platform. Frozen.

registered_byrequired string | null

The id of the user (a person or a service account) who registered the project; null when that was not recorded.

short_namerequired string

Lowercase letters and digits, unique on the platform. Frozen.

statusrequired string

Read-only. planned until provisioning starts, active once every stage is done; also provisioning, paused and retired.

one of planned, provisioning, active, paused, retired
tenant_idrequired string

The owning tenant. Frozen.

warnings array of ApiWarning

What did not go as planned on this request, which still succeeded; empty when everything did. Show these to a person.

default []
windows_vm_count_dev integer

Windows Server VMs in DEV, 0-10. VM backend only.

min 0 · max 10 · default 0
windows_vm_count_prod integer

Windows Server VMs in PROD, 0-10. VM backend only.

min 0 · max 10 · default 0
windows_vm_count_uat integer

Windows Server VMs in UAT, 0-10. VM backend only.

min 0 · max 10 · default 0
www_template string

What seeds the web site's repository: template-www (an information site; default) or template-blog (articles in Markdown, with feeds). Ignored without enable_static_site.

one of template-www, template-blog · default "template-www"

Used by post/projects, get/projects/{project_id}

ProjectCreate

object

A new project: registered and its manifest compiled. Provisions nothing: POST /projects/{id}/provisioning does.

NameTypeDescription
allow_public_https_egress boolean

Kubernetes projects: allow egress to public HTTPS.

default false
api_exposure string

Who reaches the PROD API: INTERNAL_ONLY (default) or PUBLIC. The UAT and DEV APIs are never public.

one of INTERNAL_ONLY, PUBLIC · default "INTERNAL_ONLY"
app_gateway string

shared rides the environment's app gateway; dedicated gets its own.

one of shared, dedicated · default "shared"
deployment_backend string

k8s (default): namespaces on the shared Kubernetes clusters; vm: virtual machines of its own. Frozen.

one of vm, k8s · default "k8s"
description string | null

Free text, up to 2000 characters.

max length 2000
enable_ai boolean

An AI endpoint at ai.<primary_domain>. Also allows outbound HTTPS to the internet, as allow_public_https_egress does.

default false
enable_cache boolean

An in-memory key-value cache.

default false
enable_dr_db_replica boolean

A disaster-recovery replica of the PROD database.

default true
enable_dr_object_storage_mirror boolean

A disaster-recovery mirror of the PROD object storage.

default true
enable_fullstack_app boolean

An application: its front end at app.<primary_domain> and its API at api.<primary_domain>, in PROD, UAT and DEV.

default true
enable_iis boolean

IIS/.NET hosting. VM backend only.

default false
enable_mssql boolean

SQL Server. VM backend only.

default false
enable_nas_object_storage_replication boolean

Replication of the object storage to the central store: recorded, not acted on yet.

default false
enable_object_storage boolean

Object storage for the project; false provisions none (a database-only project).

default true
enable_static_site boolean

A web site at www.<primary_domain> (and uat.www., dev.www.), seeded from www_template.

default true
enable_uat_app_public boolean

Make the UAT front end (uat.app.) reachable from the internet, e.g. to share a preview. DEV is never public.

default false
enable_uat_www_public boolean

Make the UAT web site (uat.www.) reachable from the internet.

default false
enable_web_www boolean

The web site ships from its own <gitlab_repo_slug>-www repository. Provisioning does not read it: the web site, its repository and its stages follow enable_static_site alone. With false, the platform's security scans leave the web site out, and a project with no application drops out of the traffic views. Keep it true (the default) unless the web site is not built from that repository.

default true
frontend_exposure string

Who reaches the PROD front end: PUBLIC (the internet; default) or INTERNAL_ONLY.

one of INTERNAL_ONLY, PUBLIC · default "PUBLIC"
frontend_variant string

The front-end framework the application is generated with: react (default), angular, vue or nuxt4.

one of react, angular, vue, nuxt4 · default "react"
github_repo_url string | null

A GitHub repository URL, recorded in the project's manifest as its mirror.

github_user string | null

A GitHub user name, recorded with the project.

gitlab_repo_slugrequired string

The repository name in the customer's GitLab group; unique within the customer. Frozen.

pattern ^[a-z][a-z0-9-]{1,40}$
has_mobile boolean

The project has a mobile app. Its PROD API is then public whatever api_exposure says: the app calls it from the internet.

default false
import_existing_repo boolean

The GitLab repository already holds code: provisioning does not seed it from the template.

default false
long_namerequired string

The project's display name, 2-60 characters. Double quotes, apostrophes, backslashes and control characters are refused: the name is written into the project's generated files.

min length 2 · max length 60
mssql_edition string

The SQL Server edition PROD and UAT run, with enable_mssql: express (default; free), standard or enterprise (licensed through the platform operator).

one of express, standard, enterprise · default "express"
network_only boolean

Register the network zone only: no app, no web site. Forces enable_static_site and enable_fullstack_app off. Frozen.

default false
primary_domainrequired string

The domain the project's sites are named under (www., app., api., ai.). Frozen.

max length 253
prod_object_storage_disks_per_vm integer

Data disks per PROD object storage node.

one of 1, 2 · default 2
prod_object_storage_node_count integer

PROD object storage nodes. With enable_object_storage, nodes times prod_object_storage_disks_per_vm must be at least 4.

one of 2, 4 · default 2
project_index integer | null

The third octet of the project's networks, estate-wide unique. Omit it and the server allocates one above the highest in use (never below 4). Frozen.

min 1 · max 99
short_namerequired string

Lowercase letters and digits, 2-11, starting with a letter. Estate-wide unique. Frozen.

pattern ^[a-z][a-z0-9]{1,10}$
tenant_idrequired string

The owning tenant. Frozen.

pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
windows_vm_count_dev integer

Windows Server VMs in DEV, 0-10. VM backend only.

min 0 · max 10 · default 0
windows_vm_count_prod integer

Windows Server VMs in PROD, 0-10. VM backend only.

min 0 · max 10 · default 0
windows_vm_count_uat integer

Windows Server VMs in UAT, 0-10. VM backend only.

min 0 · max 10 · default 0
www_template string

What seeds the web site's repository: template-www (an information site; default) or template-blog (articles in Markdown, with feeds). Ignored without enable_static_site.

one of template-www, template-blog · default "template-www"

Used by post/projects

ProjectMember

object

A person's role on one project (in addition to what their tenant membership gives them).

NameTypeDescription
created_at string (date-time) | null

When the role was given; null on a legacy row.

gitlab_role string | null

RECORDED, NOT ENFORCED: nothing creates the GitLab user or its GitLab membership from this value.

one of guest, reporter, developer, maintainer
project_idrequired string

The project.

rolerequired string

owner, admin, developer, member or viewer.

one of owner, admin, developer, member, viewer
user_idrequired string

The member.

Used by get/projects/{project_id}/members/{user_id}, put/projects/{project_id}/members/{user_id}

Part of ProjectMemberPage

ProjectMemberPage

object

One page of a project's members. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of ProjectMember

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/projects/{project_id}/members

ProjectMemberPut

object

The member's role on the project.

NameTypeDescription
gitlab_role string | null

Recorded, not enforced. maintainer is refused for a person who is not ATAILA staff.

one of guest, reporter, developer, maintainer
role string

owner, admin, developer (default), member or viewer.

one of owner, admin, developer, member, viewer · default "developer"

Used by put/projects/{project_id}/members/{user_id}

ProjectOutputs

object

What the project's compiled manifest names, curated: never an internal address, a machine's host name or a production secrets store path.

NameTypeDescription
gitlab_repositories array of GitLabRepository

The project's repositories in GitLab.

default []
image_registry_namespace string | null

The project's namespace in the platform's image registry.

kubernetes_namespaces array of KubernetesNamespace

Kubernetes backend: its namespaces, one per environment.

default []
secret_paths array of SecretPath

dev and uat only. A VM-backend project's paths embed its machines' host names and are not listed.

default []
urlsrequired ProjectUrls

The project's public URLs.

Part of Project,ProjectUpdated

ProjectPage

object

One page of projects (summaries: read one project for its outputs). next_cursor reads the next page.

NameTypeDescription
itemsrequired array of ProjectSummary

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/projects

ProjectPatch

object

JSON Merge Patch (RFC 7396): a member that is omitted keeps its current value; a member sent as null clears the field when the field is nullable (the schema marks it so), and null for any other field is a 422. A "" is a value (an empty string), not a clear. Frozen members are accepted only with the current value. status is not writable in v1.

NameTypeDescription
allow_public_https_egress boolean | null

Kubernetes projects: allow egress to public HTTPS.

api_exposure string | null

Who reaches the PROD API: INTERNAL_ONLY (default) or PUBLIC. The UAT and DEV APIs are never public.

one of INTERNAL_ONLY, PUBLIC
app_gateway string | null

shared rides the environment's app gateway; dedicated gets its own.

one of shared, dedicated
deployment_backend string | null

Frozen.

one of vm, k8s
description string | null

null clears it.

max length 2000
enable_ai boolean | null

An AI endpoint at ai.<primary_domain>. Also allows outbound HTTPS to the internet, as allow_public_https_egress does.

enable_cache boolean | null

An in-memory key-value cache.

enable_dr_db_replica boolean | null

A disaster-recovery replica of the PROD database.

enable_dr_object_storage_mirror boolean | null

A disaster-recovery mirror of the PROD object storage.

enable_fullstack_app boolean | null

An application: its front end at app.<primary_domain> and its API at api.<primary_domain>, in PROD, UAT and DEV.

enable_iis boolean | null

IIS/.NET hosting. VM backend only.

enable_mssql boolean | null

SQL Server. VM backend only.

enable_nas_object_storage_replication boolean | null

Replication of the object storage to the central store: recorded, not acted on yet.

enable_object_storage boolean | null

Object storage for the project; false provisions none (a database-only project).

enable_static_site boolean | null

A web site at www.<primary_domain> (and uat.www., dev.www.), seeded from www_template.

enable_uat_app_public boolean | null

Make the UAT front end (uat.app.) reachable from the internet, e.g. to share a preview. DEV is never public.

enable_uat_www_public boolean | null

Make the UAT web site (uat.www.) reachable from the internet.

enable_web_www boolean | null

The web site ships from its own <gitlab_repo_slug>-www repository. Provisioning does not read it: the web site, its repository and its stages follow enable_static_site alone. With false, the platform's security scans leave the web site out, and a project with no application drops out of the traffic views. Keep it true (the default) unless the web site is not built from that repository.

frontend_exposure string | null

Who reaches the PROD front end: PUBLIC (the internet; default) or INTERNAL_ONLY.

one of INTERNAL_ONLY, PUBLIC
frontend_variant string | null

The front-end framework the application is generated with: react (default), angular, vue or nuxt4.

one of react, angular, vue, nuxt4
github_repo_url string | null

A GitHub repository URL, recorded in the project's manifest as its mirror. null clears it.

github_user string | null

A GitHub user name, recorded with the project. null clears it.

gitlab_repo_slug string | null

Frozen.

has_mobile boolean | null

The project has a mobile app. Its PROD API is then public whatever api_exposure says: the app calls it from the internet.

import_existing_repo boolean | null

The GitLab repository already holds code: provisioning does not seed it from the template.

long_name string | null

The project's display name, 2-60 characters. Double quotes, apostrophes, backslashes and control characters are refused: the name is written into the project's generated files.

min length 2 · max length 60
mssql_edition string | null

The SQL Server edition PROD and UAT run, with enable_mssql: express (default; free), standard or enterprise (licensed through the platform operator).

one of express, standard, enterprise
network_only boolean | null

Frozen.

primary_domain string | null

Frozen.

prod_object_storage_disks_per_vm integer | null

Data disks per PROD object storage node.

one of 1, 2
prod_object_storage_node_count integer | null

PROD object storage nodes. With enable_object_storage, nodes times prod_object_storage_disks_per_vm must be at least 4.

one of 2, 4
project_index integer | null

Frozen.

short_name string | null

Frozen.

tenant_id string | null

Frozen.

windows_vm_count_dev integer | null

Windows Server VMs in DEV, 0-10. VM backend only.

min 0 · max 10
windows_vm_count_prod integer | null

Windows Server VMs in PROD, 0-10. VM backend only.

min 0 · max 10
windows_vm_count_uat integer | null

Windows Server VMs in UAT, 0-10. VM backend only.

min 0 · max 10
www_template string | null

What seeds the web site's repository: template-www (an information site; default) or template-blog (articles in Markdown, with feeds). Ignored without enable_static_site.

one of template-www, template-blog

Used by patch/projects/{project_id}

ProjectSummary

object

A project as a list shows it: no outputs, no settings.

NameTypeDescription
created_atrequired string (date-time)

When the project was registered.

customer_idrequired string | null

The tenant's customer; null only for a tenant no customer owns.

deployment_backendrequired string

k8s (default): namespaces on the shared Kubernetes clusters; vm: virtual machines of its own. Frozen.

one of vm, k8s
gitlab_repo_slugrequired string

The repository name in the customer's GitLab group. Frozen.

idrequired string

The project's id.

is_selfrequired boolean

One of ATAILA's own platform projects: readable, never writable through v1.

long_namerequired string

The project's display name, 2-60 characters. Double quotes, apostrophes, backslashes and control characters are refused: the name is written into the project's generated files.

network_onlyrequired boolean

Only the network zone is registered: no application and no web site. Frozen.

primary_domainrequired string

The domain the project's sites are named under (www., app., api., ai.). Frozen.

project_indexrequired integer

The third octet of the project's networks; unique on the platform. Frozen.

short_namerequired string

Lowercase letters and digits, unique on the platform. Frozen.

statusrequired string

Read-only. planned until provisioning starts, active once every stage is done; also provisioning, paused and retired.

one of planned, provisioning, active, paused, retired
tenant_idrequired string

The owning tenant. Frozen.

Part of ProjectPage

ProjectUpdated

object

The project after a change, with the provisioning stages the change left stale.

NameTypeDescription
allow_public_https_egress boolean

Kubernetes projects: allow egress to public HTTPS.

default false
api_exposure string

Who reaches the PROD API: INTERNAL_ONLY (default) or PUBLIC. The UAT and DEV APIs are never public.

one of INTERNAL_ONLY, PUBLIC · default "INTERNAL_ONLY"
app_gateway string

shared rides the environment's app gateway; dedicated gets its own.

one of shared, dedicated · default "shared"
created_atrequired string (date-time)

When the project was registered.

customer_idrequired string | null

The tenant's customer; null only for a tenant no customer owns.

deployment_backendrequired string

k8s (default): namespaces on the shared Kubernetes clusters; vm: virtual machines of its own. Frozen.

one of vm, k8s
description string | null

Free text, up to 2000 characters.

max length 2000
enable_ai boolean

An AI endpoint at ai.<primary_domain>. Also allows outbound HTTPS to the internet, as allow_public_https_egress does.

default false
enable_cache boolean

An in-memory key-value cache.

default false
enable_dr_db_replica boolean

A disaster-recovery replica of the PROD database.

default true
enable_dr_object_storage_mirror boolean

A disaster-recovery mirror of the PROD object storage.

default true
enable_fullstack_app boolean

An application: its front end at app.<primary_domain> and its API at api.<primary_domain>, in PROD, UAT and DEV.

default true
enable_iis boolean

IIS/.NET hosting. VM backend only.

default false
enable_mssql boolean

SQL Server. VM backend only.

default false
enable_nas_object_storage_replication boolean

Replication of the object storage to the central store: recorded, not acted on yet.

default false
enable_object_storage boolean

Object storage for the project; false provisions none (a database-only project).

default true
enable_static_site boolean

A web site at www.<primary_domain> (and uat.www., dev.www.), seeded from www_template.

default true
enable_uat_app_public boolean

Make the UAT front end (uat.app.) reachable from the internet, e.g. to share a preview. DEV is never public.

default false
enable_uat_www_public boolean

Make the UAT web site (uat.www.) reachable from the internet.

default false
enable_web_www boolean

The web site ships from its own <gitlab_repo_slug>-www repository. Provisioning does not read it: the web site, its repository and its stages follow enable_static_site alone. With false, the platform's security scans leave the web site out, and a project with no application drops out of the traffic views. Keep it true (the default) unless the web site is not built from that repository.

default true
frontend_exposure string

Who reaches the PROD front end: PUBLIC (the internet; default) or INTERNAL_ONLY.

one of INTERNAL_ONLY, PUBLIC · default "PUBLIC"
frontend_variant string

The front-end framework the application is generated with: react (default), angular, vue or nuxt4.

one of react, angular, vue, nuxt4 · default "react"
github_repo_url string | null

A GitHub repository URL, recorded in the project's manifest as its mirror.

github_user string | null

A GitHub user name, recorded with the project.

gitlab_repo_slugrequired string

The repository name in the customer's GitLab group. Frozen.

has_mobile boolean

The project has a mobile app. Its PROD API is then public whatever api_exposure says: the app calls it from the internet.

default false
idrequired string

The project's id.

import_existing_repo boolean

The GitLab repository already holds code: provisioning does not seed it from the template.

default false
is_selfrequired boolean

One of ATAILA's own platform projects: readable, never writable through v1.

long_namerequired string

The project's display name, 2-60 characters. Double quotes, apostrophes, backslashes and control characters are refused: the name is written into the project's generated files.

min length 2 · max length 60
mssql_edition string

The SQL Server edition PROD and UAT run, with enable_mssql: express (default; free), standard or enterprise (licensed through the platform operator).

one of express, standard, enterprise · default "express"
network_onlyrequired boolean

Only the network zone is registered: no application and no web site. Frozen.

outputs ProjectOutputs | null

What the project's compiled manifest names; null for a project registered without one.

primary_domainrequired string

The domain the project's sites are named under (www., app., api., ai.). Frozen.

prod_object_storage_disks_per_vm integer

Data disks per PROD object storage node.

one of 1, 2 · default 2
prod_object_storage_node_count integer

PROD object storage nodes. With enable_object_storage, nodes times prod_object_storage_disks_per_vm must be at least 4.

one of 2, 4 · default 2
project_indexrequired integer

The third octet of the project's networks; unique on the platform. Frozen.

registered_byrequired string | null

The id of the user (a person or a service account) who registered the project; null when that was not recorded.

short_namerequired string

Lowercase letters and digits, unique on the platform. Frozen.

stale_stages array of string

The provisioning stages this change left stale, in apply order: stages already done whose substrate the change affects. POST /projects/{id}/provisioning re-applies them.

default []
statusrequired string

Read-only. planned until provisioning starts, active once every stage is done; also provisioning, paused and retired.

one of planned, provisioning, active, paused, retired
tenant_idrequired string

The owning tenant. Frozen.

warnings array of ApiWarning

What did not go as planned on this request, which still succeeded; empty when everything did. Show these to a person.

default []
windows_vm_count_dev integer

Windows Server VMs in DEV, 0-10. VM backend only.

min 0 · max 10 · default 0
windows_vm_count_prod integer

Windows Server VMs in PROD, 0-10. VM backend only.

min 0 · max 10 · default 0
windows_vm_count_uat integer

Windows Server VMs in UAT, 0-10. VM backend only.

min 0 · max 10 · default 0
www_template string

What seeds the web site's repository: template-www (an information site; default) or template-blog (articles in Markdown, with feeds). Ignored without enable_static_site.

one of template-www, template-blog · default "template-www"

Used by patch/projects/{project_id}

ProjectUrls

object

The project's public URLs; null where the project has no such site.

NameTypeDescription
ai string | null

The AI endpoint (ai.).

backend string | null

The application API (api.).

frontend string | null

The application front end (app.).

static string | null

The public web site (www.).

Part of ProjectOutputs

Provisioning

object

Where a project's provisioning stands, from the database only: the stages on its apply path (deferred ones left out), which are done, running, failed, stale or waiting for an operator, and the orchestration walking them, if any.

NameTypeDescription
convergedrequired boolean

Every stage is done and none is stale — done by a real or by a simulated run.

dispatch_moderequired string

dryrun: this platform fakes pipeline dispatch, so no stage is ever executed and provisioning never completes. simulate: each stage is marked done after a few seconds without running, so a walk can reach converged while provisioned stays false.

one of live, dryrun, simulate
donerequired integer

Of those, the stages whose latest run succeeded.

failed_stagesrequired array of string

The keys of the stages whose latest run failed.

message string | null

Under dryrun or simulate: what that means for this project's provisioning, for a person; null under live.

needs_action_stagesrequired array of string

The keys of the stages waiting for an operator in the portal (manual).

orchestration Orchestration | null

The orchestration running on the project, if any.

percentrequired integer

Done stages as a share of total, 0-100, rounded.

project_idrequired string

The project.

provisionedrequired boolean

Converged, and on real runs only: no stage is simulated. The one field that says the substrate exists.

running_stagesrequired array of string

The keys of the stages running now.

simulatedrequired boolean

At least one stage's latest run was SIMULATED (dispatch_mode simulate): marked done, never run.

stagesrequired array of StageState

Every stage that counts, in catalogue order.

stale_stagesrequired array of string

The keys of the stages done against an older manifest, in apply order: the next provisioning start re-applies exactly these.

staterequired string

not_started (no stage done), provisioning (some done or running), complete (every stage done), attention (a stage failed) or needs_action (a stage needs an operator in the portal). A failure outranks a stage needing an operator. Deferred stages do not count.

one of not_started, provisioning, complete, attention, needs_action
totalrequired integer

The stages that count (every stage but the deferred ones).

Used by get/projects/{project_id}/provisioning

ReleaseOperation

object

One release-management operation: a promotion (promote_build) or a data copy (copy_data, booked in the portal only).

NameTypeDescription
approval_reason string | null

The requester's reason and the approver's note, as recorded.

completed_at string (date-time) | null

When it ended (succeeded or failed); null until then.

component string | null

What is promoted: app-api or www; null for a data copy.

one of app-api, www
decided_at string (date-time) | null

When it was approved or rejected; null when no person decided it.

decided_by string | null

Who approved or rejected it.

error_reason string | null

Why it failed or was rejected. Host addresses and digests are masked.

idrequired string

The release operation's id (/release-operations/{id}).

operationrequired string

promote_build (a promotion) or copy_data (a data copy, booked in the portal only).

one of promote_build, copy_data
operation_idrequired string

release:<id>, for GET /operations/{operation_id}.

pipeline_url string | null

The pipeline that carries it out, once known.

portal_statusrequired string

Release management's own status.

one of pending, approved, rejected, running, succeeded, failed
project_idrequired string

The project.

requested_atrequired string (date-time)

When it was requested.

requested_byrequired string

E-mail of the principal that asked (for a service account, its service address), or ci:<repo>@<commit>.

requested_token_id string | null

The API token used, when one was.

requested_via string | null

How the request was made through /api/v1. Null: booked in the portal or by a pipeline.

one of session, pat, service_account
source_envrequired string

Where it comes from: the environment below the target (sandbox for dev, where a named build is deployed; dev for uat; uat for prod).

one of sandbox, dev, uat, prod
started_at string (date-time) | null

When the pipeline started carrying it out; null until then.

statusrequired string

awaiting_approval: a PROD request waiting for a person in the portal. pending: approved, not yet picked up. failed also covers a rejected request (portal_status = rejected) and an operation the portal gave up on after hearing nothing (error_reason says so).

one of pending, awaiting_approval, running, succeeded, failed
target_envrequired string

Where it goes.

one of sandbox, dev, uat, prod
version string | null

The version promoted (an image tag); null for a data copy.

Used by get/release-operations/{release_operation_id}

Part of ReleaseOperationPage

ReleasePromotionCreate

object

Request a promotion of one component into one environment.

dev deploys a named build and needs version; the API cannot verify that the build exists before dispatch. uat and prod promote what the environment below LAST REPORTED running (dev for uat, uat for prod): omit version to take it, or give it and it must be that version.

NameTypeDescription
componentrequired string

What to promote: app-api (the application and its API) or www (the web site).

one of app-api, www
target_envrequired string

Where to: dev, uat or prod. A prod promotion waits for a person to approve it in the portal.

one of dev, uat, prod
version string | null

Required for dev, where it names a build that the API cannot verify exists before dispatch. For uat and prod: omitted means the version the source environment last reported; given, it must equal that version (422 version_not_at_source otherwise).

pattern ^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$

Used by post/projects/{project_id}/release-promotions

ReleaseState

object

Where a project's releases stand: what each environment last reported running, the PROD data lock, and the release operations still open.

NameTypeDescription
deployment_backendrequired string

Only k8s projects accept promotion requests through the API.

one of k8s, vm
in_flight_operation_idsrequired array of string

release:<id> of every operation approved or running.

pending_operation_idsrequired array of string

release:<id> of every operation awaiting approval.

prior_prod_data_copiesrequired integer

Succeeded data copies into PROD, all time.

prod_data_lockedrequired boolean

The PROD DATA lock: while set, no data copy may target PROD. It does not block code promotion.

prod_data_locked_at string (date-time) | null

When the PROD data lock was set; null while it is not.

prod_data_locked_by string | null

Who set the PROD data lock (an e-mail address, as recorded); null while it is not set.

project_idrequired string

The project.

versionsrequired array of ReportedVersion

Last reported versions, per environment and component.

Used by get/projects/{project_id}/release-state

ReportedVersion

object

What a release pipeline LAST REPORTED for one environment and component. Not a live probe: the portal records it when a deploy reports success.

NameTypeDescription
componentrequired string

app-api (the application and its API), www (the web site) or database.

one of app-api, www, database
envrequired string

The environment.

one of sandbox, dev, uat, prod
last_reported_atrequired string (date-time)

When it reported it.

last_reported_byrequired string

An operator's e-mail or pipeline:<id>.

last_reported_versionrequired string

The version the pipeline reported running.

source_env string | null

The environment it was promoted from.

one of sandbox, dev, uat, prod

Part of ReleaseState

RoleGrant

object

A role a person holds.

NameTypeDescription
granted_at string (date-time) | null

When it was granted; null when that was not recorded.

rolerequired string

The role's name as the roles catalogue spells it: a permission key (GET /permissions) or a role name such as user or admin.

user_idrequired string

The person.

warnings array of ApiWarning

What did not go as planned on this request, which still succeeded; empty when everything did. Show these to a person.

Used by get/users/{user_id}/roles/{role}, put/users/{user_id}/roles/{role}

Part of RoleGrantPage

RoleGrantPage

object

One page of a user's role grants. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of RoleGrant

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/users/{user_id}/roles

SecretPath

object

Where one non-production environment of the project keeps its secrets in the platform's secrets store.

NameTypeDescription
envrequired string

The environment: dev or uat.

one of dev, uat
pathrequired string

The location in the secrets store.

Part of ProjectOutputs

ServingTier

object

A serving tier: a stable capability name (general, code, …) that clients call as the model name, backed at any moment by one loaded model: the pinned one, or one assigned automatically from the tier's category. Tiers exist only as the platform ships them; a client can pin, unpin, enable and disable one.

NameTypeDescription
candidate_modelsrequired array of string

Every model loaded on the fleet right now: the values pinned_model may take without allow_unloaded_pin.

categoryrequired string

The group automatic assignment picks a model from, e.g. chat, code, reason, vision, embed or agent. Other values may appear.

created_atrequired string (date-time)

When the tier entered the catalogue.

enabledrequired boolean

The tier is offered to clients. A disabled tier is never served, even when a model backs it.

keyrequired string

The tier's name: the model name clients send to the gateway, and an entry of a key's models.

labelrequired string

The name the portal shows for the tier.

pinned_modelrequired string | null

Served model name; null = auto-assign.

resolvedrequired boolean

A loaded model backs the tier right now.

resolved_modelrequired string | null

The served model backing it right now.

role string | null

What the tier is for, in a few words, e.g. agentic coder.

sortrequired integer

The order within the category, lowest first; the first tier of a category is filled first when assigning automatically.

sourcerequired string

pin: the pin is loaded and serves; auto: auto-assigned; pin-offline: pinned to a model that is not loaded, so the tier is hidden; none: nothing serves it.

one of pin, auto, pin-offline, none
updated_atrequired string (date-time)

The last change; equal to created_at until the first change.

warnings array of ApiWarning

What did not go as planned on this request, which still succeeded; empty when everything did. Show these to a person.

Used by get/ai/gateway/tiers/{key}, put/ai/gateway/tiers/{key}

Part of ServingTierPage

ServingTierPage

object

One page of serving tiers. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of ServingTier

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/ai/gateway/tiers

ServingTierPut

object

Set the pin and/or the enabled flag of an EXISTING tier (tiers exist only by migration). An omitted member is left unchanged.

NameTypeDescription
allow_unloaded_pin boolean

Accept a pinned_model that is not loaded. The tier then serves nothing, and the gateway drops it, until that model is loaded.

default false
enabled boolean | null

false hides the tier from every client.

pinned_model string | null

A served model name, or null to return the tier to auto-assign. A name that is not in candidate_models is refused (model_not_loaded) unless allow_unloaded_pin is true; sending the tier's CURRENT pin is always accepted.

pattern ^[A-Za-z0-9._:/@+-]{1,200}$

Used by put/ai/gateway/tiers/{key}

SocketChain

object

Whether the census history is intact: each row's hash covers its content and the row before it, so a rewritten history shows.

NameTypeDescription
first_broken_rowrequired string | null

The id of the first census row that does not match, when not intact.

intactrequired boolean

Every row's hash matches its content and its predecessor.

rowsrequired integer

Census rows in the hash chain.

Part of SocketFacts

SocketFact

object

The latest census measurement of one node.

NameTypeDescription
cluster string | null

The virtualisation cluster the node belongs to, e.g. prod or nonprod; null when not recorded.

cores_per_socket integer | null

Cores per socket, when measured.

measured_at string (date-time) | null

When it was measured.

node_namerequired string

The node's name in its cluster.

socketsrequired integer

CPU sockets measured on the node; never zero.

sourcerequired string

Where the count came from: today always the virtualisation cluster's own report of the node. Other values may appear.

Part of SocketFacts

SocketFacts

object

The socket census: what the latest measurement of each node found, and whether the census history is intact.

NameTypeDescription
chainrequired SocketChain

The census history's hash chain.

factsrequired array of SocketFact

The latest measurement per node.

totalrequired integer | null

Sum of sockets over facts; null when no census has run.

Used by get/licence/socket-facts

StageGrid

object

Every provisioning stage of the project, deferred ones included, as the portal's Plan page shows them, from the database only.

NameTypeDescription
percentrequired integer

Done stages as a share of total, 0-100, rounded.

project_idrequired string

The project.

stagesrequired array of StageGridItem

Every stage, in catalogue order.

staterequired string

not_started (no stage done), provisioning (some done or running), complete (every stage done), attention (a stage failed) or needs_action (a stage needs an operator in the portal). A failure outranks a stage needing an operator. Deferred stages do not count.

one of not_started, provisioning, complete, attention, needs_action

Used by get/projects/{project_id}/stages

StageGridItem

object

One stage of the project's provisioning, as the portal's Plan page shows it.

NameTypeDescription
blockedrequired boolean

Pending, and a stage it depends on is not done.

deferredrequired boolean

Kept for visibility; never applied automatically.

depsrequired array of string

The keys of the stages it depends on.

error_message string | null

Why the latest run failed, as it reported it.

finished_at string (date-time) | null

When the latest run ended; null while it runs or when it has not.

keyrequired string

The stage's key, stable across runs and the same as Operation.stage.

last_run_at string (date-time) | null

When that run was created (dispatched). Null exactly when last_run_id is.

last_run_id string | null

The id of this stage's newest provisioning run in the portal's run history: the run status is taken from. A run id, not an operation id (/operations/provision:<id> names the orchestration that walked the stages). Null when the stage has never run, or when its last success was undone by a later teardown (the stage then reads pending).

simulated boolean

Its latest run was simulated.

default false
stalerequired boolean

Done against an older manifest; re-applied by the next provisioning start.

started_at string (date-time) | null

When the latest run started; null when it has not.

statusrequired string

pending, running, success, failed, partial or manual (the stage needs an operator).

one of pending, running, success, failed, partial, manual
titlerequired string

The stage's name, for a person.

verify_state string | null

The stage's latest verification, a check that what it provisioned is there: pending, running, verified, not_verified or error; null when never verified. Other values may appear.

verify_summary string | null

What that verification found, for a person.

Part of StageGrid

StageState

object

One provisioning stage of the project, and where it stands.

NameTypeDescription
keyrequired string

The stage's key, stable across runs and the same as Operation.stage.

last_run_at string (date-time) | null

When that run was created (dispatched). Null exactly when last_run_id is.

last_run_id string | null

The id of this stage's newest provisioning run in the portal's run history: the run status is taken from. A run id, not an operation id (/operations/provision:<id> names the orchestration that walked the stages). Null when the stage has never run, or when its last success was undone by a later teardown (the stage then reads pending).

simulated boolean

Its latest run was simulated.

default false
stalerequired boolean

Done against an older manifest; re-applied by the next provisioning start.

statusrequired string

pending, running, success, failed, partial or manual (the stage needs an operator).

one of pending, running, success, failed, partial, manual

Part of Provisioning

Storage

object

The model storage as last scanned: the central-store shares and each node's local disk. Nothing is scanned by reading it.

NameTypeDescription
captured_atrequired string (date-time) | null

The newest scan; null when nothing was ever scanned.

nasrequired array of StorageMount

Last scanned free space per share.

nodesrequired array of NodeStorage

Last scanned local disk per node, with its cached models.

sharesrequired array of string

The central-store shares the store actions can use.

Used by get/ai-models/storage

StorageMount

object

One storage location as last scanned: a central-store share, or a node's local disk.

NameTypeDescription
captured_at string (date-time) | null

When it was last scanned; null when never.

free_gb number (double) | null

Free space in GB, as last scanned.

kind string | null

The kind of disk, as the scan reported it: nvme, hdd or raid. Other values may appear.

mount string | null

Where the storage is mounted, as the scan reported it.

namerequired string

The share's name, or the node's hostname.

total_gb number (double) | null

Total capacity in GB, as last scanned.

Part of Storage

StoreRun

object

One run of the model store: a node cache or uncache started through this API, or an action started in the portal. The same run is the operation model-store-run:<id>.

NameTypeDescription
actionrequired string

cache / uncache (the two v1 starts), or a portal action: pull, purge, rescan, gateway-deploy, gateway-restart.

detail string | null

What the run reported last, for a person: progress, or why it failed.

dispatch_moderequired string | null

live: the runner pipeline was triggered. dryrun: this estate fakes dispatch (sandbox, or dispatch mode dryrun or simulate — a store run is never simulated); the run holds a fake pipeline id and nothing ran. Null for runs started by the portal, which does not record it.

one of live, dryrun
finished_at string (date-time) | null

When the run ended (success, failed or timeout); null while it runs.

idrequired string

The run's id.

job_started_atrequired string (date-time) | null

When the runner job started. The run's time budget counts from here, not from the dispatch.

model_id string | null

The model the run is for; null for a run that is about no one model (rescan, gateway-deploy, gateway-restart).

node string | null

The AI node the run works on (for cache and uncache, the node of the copy); null when no node is involved.

operation_idrequired string

model-store-run:<id>: poll it at /operations/{id}.

pipeline_id integer | null

The runner pipeline carrying the run out, once dispatched. Under dryrun a fake id.

pipeline_url string | null

The pipeline's page in GitLab, once known. Under dryrun it names the fake pipeline id and leads nowhere.

progress_gb number (double) | null

GB copied so far, while a copy runs; null when not reported.

reporequired string

The model's Hugging Face repo id as it was when the run started; gateway for the two gateway actions.

started_atrequired string (date-time)

When the run was recorded (dispatched).

statusrequired string

pending, running, success, failed or timeout.

triggered_by string | null

The id of the user (a person or a service account) who started the run; null when not recorded.

Used by get/ai-models/runs/{run_id}

Tenant

object

A tenant of a customer: the unit projects, memberships and AI gateway keys belong to.

NameTypeDescription
created_atrequired string (date-time)

When the tenant was registered.

customer_idrequired string | null

The owning customer's id. Null only for a legacy tenant that no customer owns; such a tenant can be read but never created through v1, where customer_id is required.

default_router_id string | null

The id of the tenant's default router; null when none is set.

description string | null

Free text, up to 2000 characters.

idrequired string

The tenant's id (a UUID).

is_primaryrequired boolean

The customer's primary tenant; it can never be deleted.

member_countrequired integer

Its members.

namerequired string

The tenant's display name.

project_countrequired integer

Its projects, retired ones included.

slugrequired string

The tenant's short name: lowercase letters, digits and -, starting with a letter. Frozen.

updated_atrequired string (date-time)

The last change; equal to created_at until the tenant is first changed, so it is never null.

Used by post/tenants, get/tenants/{tenant_id}, patch/tenants/{tenant_id}

Part of TenantPage

TenantCreate

object

A further tenant of an existing customer.

NameTypeDescription
customer_idrequired string

The customer the tenant belongs to. Frozen after create.

pattern ^[1-9][0-9]{0,8}$
default_router_id string | null

The id of the tenant's default router; null when none is set.

pattern ^[1-9][0-9]{0,8}$
description string | null

Free text, up to 2000 characters.

max length 2000
namerequired string

The tenant's display name.

min length 2 · max length 120
slugrequired string

Lowercase letters, digits and '-', starting with a letter, 2-30 characters. Frozen after create.

pattern ^[a-z][a-z0-9-]{1,29}$

Used by post/tenants

TenantPage

object

One page of tenants. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of Tenant

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/tenants

TenantPatch

object

JSON Merge Patch (RFC 7396): a member that is omitted keeps its current value; a member sent as null clears the field when the field is nullable (the schema marks it so), and null for any other field is a 422. A "" is a value (an empty string), not a clear. description and default_router_id are nullable; name is not.

NameTypeDescription
customer_id string | null

Frozen.

default_router_id string | null

null clears it.

pattern ^[1-9][0-9]{0,8}$
description string | null

Free text, up to 2000 characters. null clears it.

max length 2000
name string | null

The tenant's display name.

min length 2 · max length 120
slug string | null

Frozen.

Used by patch/tenants/{tenant_id}

User

object

A person on this platform, or a service account. Never carries a password or an SSO or GitLab identifier.

NameTypeDescription
ad_usernamerequired string | null

The Windows (directory) account name. Create-only: a PATCH may send the current value (nothing changes); any other value is 422 immutable_field, whether or not the person has an SSO account yet.

auth_moderequired string | null

Which sign-in routes the person may use. Read-only in v1.

one of sso, local, both
created_atrequired string (date-time)

When the user was created.

emailrequired string | null

The person's e-mail address and local sign-in name; unique. Stored and returned entirely LOWER-CASED (local part included), surrounding whitespace dropped, and a Name <address> form reduced to the address. Compare case-insensitively. Null only on a legacy row that never had one.

first_namerequired string | null

Null only on a legacy row created before first/last names existed.

gitlab_linkedrequired boolean

A GitLab account exists for them.

idrequired string

The user's id (a UUID).

is_activerequired boolean

False once deactivated (DELETE). PATCH with true re-activates.

is_internalrequired boolean

ATAILA staff. Read-only in v1.

kindrequired string

Read-only. service accounts are managed on the portal's service accounts page; every write on one here is a 409.

one of human, service
last_name string | null

Null when the person has none.

localerequired string

The language the portal and its e-mails use for the person: en or hu.

one of en, hu
namerequired string

first_name and last_name joined; read-only.

needs_git_accessrequired boolean

Whether the person is meant to have a GitLab account.

provisioning_statusrequired string | null

The outcome of the newest provisioning run (username, SSO account, GitLab account, GitLab group): ok; partial when a step was skipped (typically no GitLab account wanted, or no SSO configured on this platform at all: warning sso_not_configured on the create); error when a step failed, including a configured SSO that failed. Null when the person was never provisioned.

one of running, ok, partial, error
rolesrequired array of string

Every role the person holds, sorted.

sso_linkedrequired boolean

An SSO account exists for them.

sso_sync_statusrequired string

The last SSO projection of this person: unlinked (no SSO account), pending, ok or error. Writes through v1 converge the SSO account before answering; the portal also re-converges every 900 s.

one of unlinked, pending, ok, error
updated_atrequired string (date-time)

The last change; equal to created_at until the first change.

usernamerequired string | null

The sign-in handle and directory account name. Set at create (derived from the name when omitted). Create-only: a PATCH may send the current value (nothing changes); any other value is 422 immutable_field, whether or not the person has an SSO account yet.

warnings array of ApiWarning

What did not go as planned on this request, which still succeeded; empty when everything did. Show these to a person.

Used by post/users, get/users/{user_id}, patch/users/{user_id}

Part of UserPage

UserCreate

object

No password: a person created through the API cannot sign in until an operator resets their password or they reset it themselves.

NameTypeDescription
ad_username string | null

The Windows account name, when firstname.lastname is too long. Lower-case letters, digits, '.', '_' and '-', 1-20 characters, not ending in '.'. Create-only.

pattern ^[a-z0-9._-]{1,20}$
emailrequired string (email)

The person's e-mail address and local sign-in name; unique. Stored and returned entirely LOWER-CASED (local part included), surrounding whitespace dropped, and a Name <address> form reduced to the address. Compare case-insensitively.

first_namerequired string

The person's first name.

min length 1 · max length 100
last_name string | null

The person's last name; may be omitted.

max length 100
locale string

The language the portal and its e-mails use for the person: en or hu. Default hu.

one of en, hu · default "hu"
needs_git_access boolean

Create their GitLab account now (and later whenever it is switched on).

default false
username string | null

Lower-case letters, digits, '.', '_' and '-', 1-20 characters, not ending in '.'. Omit to derive firstname.lastname, folded to ASCII (or ad_username when given). Create-only.

pattern ^[a-z0-9._-]{1,20}$

Used by post/users

UserPage

object

One page of users. next_cursor reads the next page.

NameTypeDescription
itemsrequired array of User

This page's items, in the list's order.

next_cursor string | null

Send it as cursor to read the next page; null on the last page. Opaque: never build or change one.

Used by get/users

UserPatch

object

JSON Merge Patch (RFC 7396): a member that is omitted keeps its current value; a member sent as null clears the field when the field is nullable (the schema marks it so), and null for any other field is a 422. A "" is a value (an empty string), not a clear. Only last_name is nullable.

NameTypeDescription
ad_username string | null

Create-only: a PATCH may send the current value (nothing changes); any other value is 422 immutable_field, whether or not the person has an SSO account yet.

email string (email) | null

The person's e-mail address and local sign-in name; unique. Stored and returned entirely LOWER-CASED (local part included), surrounding whitespace dropped, and a Name <address> form reduced to the address. Compare case-insensitively. A change answers with a email_keyed_grants_affected warning.

first_name string | null

The person's first name.

min length 1 · max length 100
is_active boolean | null

false deactivates exactly like DELETE (same refusals, same destroy gate); true re-activates.

last_name string | null

null clears it.

min length 1 · max length 100
locale string | null

The language the portal and its e-mails use for the person: en or hu.

one of en, hu
needs_git_access boolean | null

Switching it on creates the GitLab account now. Switching it off does not remove one.

username string | null

Create-only: a PATCH may send the current value (nothing changes); any other value is 422 immutable_field, whether or not the person has an SSO account yet.

Used by patch/users/{user_id}

Whoami

object

Who is calling, how, and what they may do right now.

NameTypeDescription
auth_kindrequired string

How the caller authenticated: session (signed in to the portal), pat (a personal API token) or service_account (a service-account token). Other values may appear.

expires_at string (date-time) | null

When the credential stops working: the token's expiry, or the session's.

principalrequired WhoamiPrincipal

The calling account.

scopesrequired array of string

The permission keys in effect for this request, sorted. For a token, its scopes that its owner still holds; for a portal session, the account's roles.

token WhoamiToken | null

The token, when the credential is one; null for a portal session.

Used by get/whoami

WhoamiPrincipal

object

The account behind the credential.

NameTypeDescription
emailrequired string

The account's e-mail address; a service account's is a synthetic address that receives no mail.

idrequired string

The account's user id.

kindrequired string

human (a person) or service (a service account). Other values may appear.

namerequired string

The account's display name.

Part of Whoami

WhoamiToken

object

The API token this request was made with.

NameTypeDescription
allow_destroyrequired boolean

The token may archive, delete, deactivate and retire; without it those operations answer 403 destroy_not_allowed.

granted_scopesrequired array of string

The scopes the token was created with. What it may do now is scopes on the answer: these, less any its owner no longer holds.

idrequired string

The token's id, as the audit log records it (token_id).

namerequired string

The name the token was given when it was created.

prefixrequired string

The token's public prefix, which the portal shows to tell tokens apart. Never the secret part.

Part of Whoami

Rendered from openapi-v1.json, platform release 1.0.187.