AMD AI Workbench API reference OpenAPI Swagger

AI Workbench API Reference

This page documents the public AMD AI Workbench API: a supported, versioned contract intended for direct use by clients. The endpoints below cover AIM (AMD Inference Microservice) deployment and management, and fine-tuning. Their behavior and structure are stable and maintained with backward compatibility within a given API version; breaking changes go through explicit versioning or deprecation.

Endpoints not listed here — including those used internally by the AI Workbench frontend — are implementation details. They are not part of this contract and may change without notice.

To call any endpoint you need a Keycloak bearer token — see Keycloak Authentication for the user-session flow and Session Lifetime for refreshing it.

API keys are a separate, longer-lived credential used to authenticate against the OpenAI-compatible inference endpoints exposed by deployed models — they do not grant access to the management API documented here.

Interactive Swagger UI

Every AI Workbench deployment also ships an interactive Swagger UI, which is the best way to try endpoints against a live environment:

• Swagger UI: https://<workbench-host>/docs

• Raw OpenAPI specification: https://<workbench-host>/openapi.json

Note that the live Swagger UI reflects the full deployed surface, including internal endpoints; only the endpoints documented on this page are part of the public contract. Obtain <workbench-host> from your platform administrator — the hostname is environment-specific.

What This API Covers

• Inference (AIM deployment & management) — browse the inference base model catalog and AIM profiles; deploy a model with optional LoRA adapters attached, list and inspect deployments, change the attached adapters on a running deployment, adjust scaling, inspect replicas and metrics, and undeploy.

• Fine-tuning — browse fine-tunable base models; start and cancel full or LoRA fine-tuning jobs; list, inspect, and delete the resulting fine-tuned models.

Limitations

• Adapter artifact management is not part of this API version. Uploading, listing, inspecting, or deleting adapter artifacts directly is not exposed by the public contract. Adapters can only be referenced by name when deploying or patching an inference deployment. A LoRA fine-tuning job can also be configured to keep its output as an adapter rather than a merged model, but that adapter is likewise not manageable through this API once produced.

Endpoint Reference

The complete endpoint and schema reference below is generated directly from the service’s OpenAPI specification and filtered to the public contract, so it always matches the supported API. All request and response bodies use camelCase field names.

Authentication

Security Schemes

Name	Type	Description	Scheme	Bearer Format
OpenIdAuthorization	openIdConnect

APIs

GET /v1/inference/models

List inference base models

List the cluster’s catalog of base models that can be deployed for inference as a paginated envelope (default page size 10, max 100). Use ?page= and ?pageSize= to navigate; the response includes a pagination object with page, pageSize, and total alongside data.

Use the statusFilter query parameter (repeatable) to return only models with matching statuses, e.g. ?statusFilter=Ready&statusFilter=Failed.

Use ?acceleratorType= to narrow the catalog to AIMs whose published hardware footprints include that accelerator family — useful for picking out EPYC-only or GPU-only models for the deploy picker. The parameter is repeatable to OR multiple values, e.g. ?acceleratorType=cpu&acceleratorType=gpu. An AIM matches when any entry in its status.discoveredProfiles.byHardware[] list has a matching acceleratorType. Values are case-sensitive lowercase; AIMs with no published hardware are excluded when this filter is set.

Pagination is applied after the filters, so total reflects only the matching models.

Parameters

Name	Type	Required	Description
page	integer	False
pageSize	integer	False
statusFilter		False	Filter base models by status (repeatable), e.g. ?statusFilter=Ready&statusFilter=Failed.
acceleratorType		False	Filter base models by accelerator family. Repeat to OR multiple values, e.g. ?acceleratorType=cpu&acceleratorType=gpu. Case-sensitive lowercase values: cpu or gpu. Models with no published hardware are excluded when this filter is set.

Responses

200

Successful Response

InferenceModelsList

401

Missing or invalid authentication token.

403

Token is valid but missing required claims (e.g. email).

422

Validation Error

HTTPValidationError

GET /v1/inference/models/{name}

Get an inference base model

Get a single base model from the cluster catalog by its resource name (AIMClusterModel metadata.name).

Parameters

Name	Type	Required	Description
name	string	True	AIMClusterModel resource name

Responses

200

Successful Response

AIMResponse

401

Missing or invalid authentication token.

403

Token is valid but missing required claims (e.g. email).

404

AIM cluster model not found.

422

Validation Error

HTTPValidationError

GET /v1/inference/profiles

List inference base model profiles

List AIMClusterProfile resources as a paginated envelope (default page size 10, max 100). Use ?page= and ?pageSize= to navigate.

Pass ?aimId=<canonical-id> to narrow the result set. The query parameter is repeatable to batch several models into one round-trip (?aimId=meta-llama/Llama-3&aimId=Cohere/cmd-a). The aimId corresponds to the AIMClusterModel’s status.aimId (e.g. CohereLabs/command-a-reasoning-08-2025) and matches each profile’s spec.aimId. Callers should prefer the aimId they already have from the catalog response rather than indirecting through a resource name — the engine reconciles status.aimId asynchronously.

Each profile captures a pre-validated serving configuration for the model: optimization metric (latency vs throughput), accelerator model and count, precision, and an availability flag that reflects whether the cluster currently has the hardware to run it.

Returns 200 + empty data when no profiles match — no 404 is emitted for an unknown aimId.

Parameters

Name	Type	Required	Description
page	integer	False
pageSize	integer	False
aimId		False	Filter by canonical model architecture identifier (matches profile spec.aimId). Repeatable to OR multiple values, e.g. ?aimId=meta-llama/Llama-3&aimId=Cohere/cmd-a. Max 50 values per request.

Responses

200

Successful Response

InferenceProfilesList

401

Missing or invalid authentication token.

403

Token is valid but missing required claims (e.g. email).

422

Validation Error

HTTPValidationError

GET /v1/inference/profiles/{name}

Get a single inference base model profile

Fetch a single AIMClusterProfile by resource name. Designed for targeted lookups where the caller already knows the profile name (e.g. the AIM detail page joining AIMService.status.resolvedProfile.name) — avoids the aimId derivation hop required by the listing endpoint.

Parameters

Name	Type	Required	Description
name	string	True	AIMClusterProfile resource name (metadata.name).

Responses

200

Successful Response

AIMProfileResource

401

Missing or invalid authentication token.

403

Token is valid but missing required claims (e.g. email).

404

AIMClusterProfile not found.

422

Validation Error

HTTPValidationError

POST /v1/projects/{project}/inference

Deploy a model for inference

Deploy a model for inference in the given project.

The model field accepts either an AIMClusterModel name (cluster-scoped) or an AIMModel name (project-scoped fine-tuned or custom-onboarded model). The API auto-detects which type it is.

For a custom-onboarded model, profileName selects which of that model’s profiles serves the deployment, using an identifier from its profile list (default selects the engine-provided profile). The server resolves it to the profile that identifier derives and pins it, so the deployment keeps serving that profile rather than re-resolving to a sibling. Omitting profileName deploys the Default. Fine-tuned models have no selectable profiles and continue to reject it.

adapters attaches the project’s LoRA adapters to the deployment by name. Each one must be an adapter in this project, must list the deployed model among the base models it can serve, and — for adapters uploaded here — must have finished uploading its weights. If any adapter fails a check the whole deploy is refused with a 400 naming each one and why, and nothing is created.

adapterMode is immutable once the deployment exists, so it can only be chosen here. Omit it to take the platform default (static, serving exactly the adapters listed at deploy time).

A pinned profile must support serving adapters whenever the deployment will need that capability — either because adapters names some, or because adapterMode is dynamic, which asks for adapters to be attachable while the deployment runs and so is refused on an incapable profile even when no adapters are named. On the selector path no profile is pinned and the engine makes that call instead, after the deployment is created.

Per-adapter progress appears on status.adapters of the deployment exactly as the engine reports it; the platform neither derives nor aggregates it.

Parameters

Name	Type	Required	Description
project	string	True	Project identifier (workbench namespace name).

Request Body

InferenceDeployRequest

Responses

202

Successful Response

InferenceDeploymentResponse

401

Missing or invalid authentication token.

403

Caller does not have access to the project, or the project is not a workbench namespace.

404

Project or namespace not found, or referenced model resource not found.

400

Model requires a Hugging Face token but none was provided; profileName is unknown to the model or names a profile that is not ready; profileName was supplied for a fine-tuned model; imagePullSecrets/hfToken were supplied for a project-scoped model; a requested adapter cannot be attached to this model or profile; or adapterMode is dynamic and the pinned profile cannot serve adapters.

422

Invalid scaling policy (e.g., missing one of minReplicas/maxReplicas/autoScaling, or maxReplicas < minReplicas), or an invalid adapters list (more than 64 adapters, the same adapter listed twice, or a name no adapter artifact could have).

GET /v1/projects/{project}/inference

List inference deployments

List inference deployments in the project as a paginated envelope (default page size 10, max 100). Use ?page= and ?pageSize= to navigate; the response includes a pagination object with page, pageSize, and total alongside data.

Use ?capability=chat to narrow the list to deployments whose model supports chat completions and whose serving stack is fully ready — useful for populating chat-target pickers. Use ?statusFilter= to filter by deployment status (repeatable). Pagination is applied after capability and status filters, so total reflects the filtered set.

Including statusFilter=Deleted also surfaces DB-persisted historical deployments (undeployed AIMServices), merged into the same paginated data list. Historical entries carry statusValue: "Deleted", empty endpoints, and the original deployment’s id, model and creationTimestamp; the live K8s engine never emits the Deleted status itself.

Note: capability=chat requires the serving stack to be fully ready, so combining it with statusFilter=Pending (or other non-ready statuses) will typically return an empty list.

Parameters

Name	Type	Required	Description
project	string	True	Project identifier (workbench namespace name).
page	integer	False
pageSize	integer	False
capability		False	Filter deployments by capability. Currently only chat is supported and returns deployments whose model supports chat completions and whose serving stack is fully ready.
statusFilter		False	Optional filter by deployment status (repeatable).

Responses

200

Successful Response

InferenceDeploymentsList

401

Missing or invalid authentication token.

403

Caller does not have access to the project, or the project is not a workbench namespace.

404

Project or namespace not found.

422

Validation Error

HTTPValidationError

GET /v1/projects/{project}/inference/{id}

Get an inference deployment

Get a single inference deployment by ID.

The response includes endpoints.internal, the in-cluster URL used by the AIWB UI’s chat bypass for direct inference calls.

Parameters

Name	Type	Required	Description
id	string	True	The UUID of the inference deployment
project	string	True	Project identifier (workbench namespace name).

Responses

200

Successful Response

InferenceDeploymentResponse

401

Missing or invalid authentication token.

403

Caller does not have access to the project, or the project is not a workbench namespace.

404

Project or namespace not found, or inference deployment not found in the project.

502

The cluster could not be reached, or refused the request for a reason it did not attribute to the request.

422

Validation Error

HTTPValidationError

PATCH /v1/projects/{project}/inference/{id}

Update an inference deployment

Update an inference deployment without redeploying the model.

Two changes are supported, either on its own or both together:

• Scaling policy. All three fields (minReplicas, maxReplicas, autoScaling) must be provided together.

• Adapters. adapters is the complete set the deployment should serve: adapters currently attached and not listed are detached, and [] detaches all of them. Omit the field to leave the adapter set alone.

A request carrying both reaches Kubernetes as a single atomic update: either both changes are recorded or neither is.

Changing adapters requires the deployment to have been created with adapterMode: dynamic, which is fixed at deploy time — a deployment created without it can never accept an adapter change. Each requested adapter passes the same checks as at deploy time: it must be an adapter in this project, must list the deployed model among the base models it can serve, and — for adapters uploaded here — must not be waiting on an unfinished upload. That last check only ever refuses on a definite “the weights are not there”; storage that cannot be reached leaves it unknown and the change proceeds. If any check fails, the request is refused with a 400 naming each one and why, and nothing is changed. A scaling-only request is not subject to adapterMode and works on any deployment.

Accepting this request records the requested set on the deployment; it does not mean the adapters are serving traffic yet. spec.adapters is what was requested and status.adapters[] is what the engine reports, verbatim — the platform neither derives nor aggregates it. The state on each entry is that adapter’s disk-side staging state: Downloaded means its weights are present, which is not a load confirmation and must not be read as one. Loaded is the authoritative signal that an adapter is available for inference wherever the engine reports it, but the engine deployed today reports disk-side states only, so the absence of Loaded is not evidence of failure. A detached adapter legitimately stays in status.adapters as Deleting until the unload completes. The engine picks up a change on its next poll, so allow up to one poll interval before the runtime reflects it.

Parameters

Name	Type	Required	Description
id	string	True	UUID of the inference deployment
project	string	True	Project identifier (workbench namespace name).

Request Body

InferencePatchRequest

Responses

200

Successful Response

InferenceDeploymentResponse

401

Missing or invalid authentication token.

403

Caller does not have access to the project, or the project is not a workbench namespace.

404

Project or namespace not found, or inference deployment not found in the project.

400

Neither adapters nor the scaling policy was supplied; the deployment’s adapterMode is not dynamic; a requested adapter cannot be attached to this deployment; or Kubernetes rejected the change.

409

The deployment changed concurrently; re-read it and retry.

422

Scaling fields are partially provided (e.g., autoScaling missing while min/max set), maxReplicas < minReplicas, or an invalid adapters list (more than 64 adapters, the same adapter listed twice, or a name no adapter artifact could have).

502

The cluster could not be reached, or refused the change for a reason it did not attribute to the request.

DELETE /v1/projects/{project}/inference/{id}

Undeploy an inference deployment

Undeploy an inference deployment by removing its AIMService from Kubernetes. Tears down associated cluster-auth groups when present.

Parameters

Name	Type	Required	Description
id	string	True	UUID of the inference deployment to undeploy
project	string	True	Project identifier (workbench namespace name).

Responses

204

Successful Response

401

Missing or invalid authentication token.

403

Caller does not have access to the project, or the project is not a workbench namespace.

404

Project or namespace not found, or inference deployment not found in the project.

502

The cluster could not be reached, or refused the request for a reason it did not attribute to the request.

422

Validation Error

HTTPValidationError

GET /v1/projects/{project}/inference/{id}/metrics/{metric}

Get an inference deployment metric

Retrieve a single inference-scoped metric for a deployment from Prometheus, identified by deployment UUID. Optionally scope to a specific replica via podName.

Parameters

Name	Type	Required	Description
id	string	True	The UUID of the inference deployment
metric	string	True	Metric name to retrieve
project	string	True	Project identifier (workbench namespace name).
podName		False	Optional pod name to scope metrics to a single replica.
start	string	True
end	string	True

Responses

200

Successful Response

401

Missing or invalid authentication token.

403

Caller does not have access to the project, or the project is not a workbench namespace.

404

Project or namespace not found, or inference deployment not found in the project.

502

The cluster could not be reached, or refused the request for a reason it did not attribute to the request.

422

Invalid metric name (not in the supported enum), or invalid time range (e.g., start >= end, or start older than the lookback window).

GET /v1/projects/{project}/inference/{id}/replicas

List inference deployment replicas

Return Kubernetes pod data for each replica of an inference deployment. The response is a fixed schema containing commonly needed pod fields (name, phase, IP, containers, resource limits, conditions).

Parameters

Name	Type	Required	Description
id	string	True	The UUID of the inference deployment
project	string	True	Project identifier (workbench namespace name).

Responses

200

Successful Response

ListResponse_InferenceReplicaResponse_

401

Missing or invalid authentication token.

403

Caller does not have access to the project, or the project is not a workbench namespace.

404

Project or namespace not found, or inference deployment not found in the project.

502

The cluster could not be reached, or refused the request for a reason it did not attribute to the request.

422

Validation Error

HTTPValidationError

GET /v1/fine-tuning/models

List finetunable base models

List base models that can be fine-tuned on the cluster’s current GPU hardware.

Only models with at least one matching recipe are returned. A recipe is considered matching when its required accelerator family is present on at least one schedulable node in the cluster, so the result set is gated by the GPUs actually installed (e.g., a cluster with only MI300X nodes will not see MI250-only recipes). Each entry reports the canonical model name, the recipe’s GPU count, and the AMD device IDs and display names of the compatible accelerators.

Responses

200

Successful Response

ListResponse_FinetunableModelResponse_

401

Missing or invalid authentication token.

403

Token is valid but missing required claims (e.g. email).

GET /v1/fine-tuning/models/{name}

Get a finetunable base model by canonical name

Look up a single finetunable base model by its canonical name (e.g., meta-llama/Llama-3.1-8B).

The name segment is declared as a path parameter with {name:path} so canonical names containing forward slashes (the standard HuggingFace org/model convention) match without URL-encoding the separator. The returned entry mirrors what GET /fine-tuning/models would emit for that model, including the compatible GPU set.

Parameters

Name	Type	Required	Description
name	string	True	Canonical name of the finetunable base model

Responses

200

Successful Response

FinetunableModelResponse

401

Missing or invalid authentication token.

403

Token is valid but missing required claims (e.g. email).

404

Finetunable model not found, or not compatible with the cluster’s GPUs.

422

Validation Error

HTTPValidationError

GET /v1/projects/{project}/fine-tuning/models

List fine-tuned models in a project

List AIMModel resources in a project that were produced by fine-tuning jobs as a paginated envelope (default page size 10, max 100). Use ?page= and ?pageSize= to navigate; the response includes a pagination object with page, pageSize, and total alongside data.

Excludes onboarded custom models (those go through /projects/{project}/models/preview) — only models whose AIMModel CR records a fine-tuning provenance are returned. The fine-tuning label filter is applied before pagination so total reflects only fine-tuned models, not the raw AIMModel count.

Parameters

Name	Type	Required	Description
project	string	True	Project identifier (workbench namespace name).
page	integer	False
pageSize	integer	False

Responses

200

Successful Response

FineTuningModelsList

401

Missing or invalid authentication token.

403

Caller does not have access to the project, or the project is not a workbench namespace.

404

Project or namespace not found.

422

Validation Error

HTTPValidationError

GET /v1/projects/{project}/fine-tuning/models/{model_id}

Get a fine-tuned model

Get a single fine-tuned model in a project.

The model_id may be either the AIMModel resource name or the UUID of the workload that produced it; the API resolves both forms to the same underlying AIMModel CR. The segment is declared as {model_id:path} so resource names containing forward slashes match without URL-encoding the separator.

Parameters

Name	Type	Required	Description
model_id	string	True	AIMModel CR resource name or workload UUID
project	string	True	Project identifier (workbench namespace name).

Responses

200

Successful Response

AIMModelResource

401

Missing or invalid authentication token.

403

Caller does not have access to the project, or the project is not a workbench namespace.

404

Project or namespace not found, or fine-tuned model not found in the project.

422

Validation Error

HTTPValidationError

DELETE /v1/projects/{project}/fine-tuning/models/{model_id}

Delete a fine-tuned model

Delete a fine-tuned model from the project.

Cascading semantics: the AIMModel CR is removed from Kubernetes and the model weights are deleted from S3 in the same operation. If active inference deployments reference the model, the request is rejected with 409; pass force=true to delete anyway (the downstream deployments will fail to reload on restart). The call is idempotent for an already-deleted model — a second DELETE returns 404.

Parameters

Name	Type	Required	Description
model_id	string	True	AIMModel CR resource name or workload UUID
project	string	True	Project identifier (workbench namespace name).
force	boolean	False	Delete even if active deployments exist

Responses

204

Successful Response

401

Missing or invalid authentication token.

403

Caller does not have access to the project, or the project is not a workbench namespace.

404

Project or namespace not found, or fine-tuned model not found in the project.

502

The cluster could not be reached, or refused the request for a reason it did not attribute to the request.

409

Active deployments reference the model; pass force=true to override.

422

Validation Error

HTTPValidationError

POST /v1/projects/{project}/fine-tuning/jobs

Start a fine-tuning job

Start a fine-tuning job in the project.

The baseModel field accepts either a HuggingFace canonical name (e.g., meta-llama/Llama-3.1-8B) or an existing AIMModel UUID to continue training from a previous fine-tune. Each entry in datasetIds must reference a dataset already uploaded into the same project — datasets from other projects are not visible. The deprecated datasetId field remains accepted for single-dataset clients.

The job is submitted asynchronously; the response carries the new workloadId. The job then transitions Pending → Running → Completed/Failed and on success produces an AIMModel CR that becomes visible via GET /projects/{project}/fine-tuning/models.

Parameters

Name	Type	Required	Description
project	string	True	Project identifier (workbench namespace name).

Request Body

FineTuningJobRequest

Responses

202

Job submitted; poll workloadId for progress.

FinetuneJobResponse

401

Missing or invalid authentication token.

403

Caller does not have access to the project, or the project is not a workbench namespace.

404

Project or namespace not found, or base model not found, or dataset not found in the project.

400

Base model has no weights URI (not fully onboarded).

422

Invalid hyperparameters or job name (pattern / range constraints).

DELETE /v1/projects/{project}/fine-tuning/jobs/{job_id}

Cancel a fine-tuning job

Cancel an in-progress fine-tuning job in the project.

Cascading semantics: the underlying Kubernetes job and its supporting components (PyTorchJob, configmaps, secrets) are torn down, but the workload row is retained for history and audit so the cancelled run remains visible in /projects/{project}/workloads. The call is idempotent: repeating it on an already-cancelled job returns 204 and re-attempts the K8s teardown (missing resources are treated as already-deleted).

Parameters

Name	Type	Required	Description
job_id	string	True	Workload UUID of the fine-tuning job
project	string	True	Project identifier (workbench namespace name).

Responses

204

Successful Response

401

Missing or invalid authentication token.

403

Caller does not have access to the project, or the project is not a workbench namespace.

404

Project or namespace not found, or fine-tuning job not found in the project.

422

Validation Error

HTTPValidationError

Components

AIMCondition

A single metav1.Condition entry, shared across AIM CRD status blocks.

Field	Type	Description
lastTransitionTime
message	string
observedGeneration
reason	string
status	string
type	string

AIMImageMetadata

Field	Type	Description
model
oci
originalLabels	object

AIMModelCustom

Custom model settings (fine-tuned / custom-weight models).

Field	Type	Description
versionPolicy
hardware
type

AIMModelDiscoveryConfig

Discovery configuration for AIMModel.

Mirrors AIMModelDiscoveryConfig in aim-engine. Controls which metadata aim-engine extracts from the source image and whether per-profile CRs are auto-created.

Field	Type	Description
extractMetadata
createServiceTemplates

AIMModelMetadata

Field	Type	Description
canonicalName
descriptionFull
hfTokenRequired
source
tags	array
title
variants	array

AIMModelProfilesDerivedFrom

Source half of the derivation — which existing profiles to copy from.

Only selector is modeled; the alternate sourceRef (discovery-cache source) is not used by the onboard flow.

Field	Type	Description
selector

AIMModelProfilesSpec

v1alpha2 spec.profiles block driving profile derivation.

version_policy / version sit here (not under derived_from) to mirror the CRD. CEL: version is required when version_policy is pinned and forbidden when it is latest/all — the onboard builder uses all and leaves version unset.

Field	Type	Description
derivedFrom
versionPolicy
version
overrides

AIMModelResource

AIMModel CRD resource (namespace- or cluster-scoped).

Cluster-scoped resources (kind AIMClusterModel) have an empty metadata.namespace; namespace-scoped resources (kind AIMModel) always carry it. The shape is otherwise identical, matching aim-engine’s Go types where one AIMModelSpec/AIMModelStatus backs both CRDs.

Field	Type	Description
metadata
spec
status

AIMModelSource

Source for model weights in an AIMModel or AIMClusterModel.

env carries per-source credential overrides (e.g. HF_TOKEN) in the v1alpha2 spec.profiles.overrides.modelSources[] shape. Left as None (rather than an empty list) so it is omitted on dump when unused — the CRD treats absent and empty differently for some sources.

Field	Type	Description
modelId	string
sourceUri	string
precision
env

AIMModelSourceEnvVar

A single environment variable applied to a model source.

name is the variable name (e.g. HF_TOKEN, AWS_ENDPOINT_URL); the value is supplied inline or from a secret reference. Additional keys such as value and valueFrom are preserved as-is so a read-modify-write of the resource does not drop credential configuration authored elsewhere.

Field	Type	Description
name

AIMModelSpec

Spec shared by AIMModel and AIMClusterModel (namespace- or cluster-scoped).

aim-engine reuses one Go AIMModelSpec for both cluster- and namespace- scoped CRDs; AIWB mirrors that. Namespace-only fields (model_sources, custom, env) are simply unused on cluster-scoped resources.

Carries both the legacy v1alpha1 flat fields (image, model_sources, env) used by fine-tuning/official flows and the v1alpha2 profiles derivation block used by custom-model onboard. CEL enforces image XOR profiles, so a single object only ever populates one shape.

Note these two shapes are NOT made exclusive by model_dump alone: image/model_sources/env default to ""/[]/[] (not None), so dumping an instance with exclude_none=True would still emit empty legacy fields alongside profiles and trip the CEL rule. Callers that build a v1alpha2 manifest must therefore emit a profiles-only spec explicitly — the custom-model onboard builder composes {"profiles": ...} from the AIMModelProfilesSpec dump rather than serializing a full AIMModelSpec. This model is still used unchanged for reading back either shape (where the populated fields are exactly what the server returned).

Field	Type	Description
aimId
image	string
imageMetadata
modelSources	array
custom
env	array
discovery
profiles

AIMModelStatus

Status of an AIM(Cluster)Model resource.

Shared between cluster-scoped and namespace-scoped AIMModel CRDs — the engine’s Go status is AIMModelStatus for both.

AIMModelStatusFields

Status for AIMModel (namespace- or cluster-scoped).

aim-engine reuses one Go AIMModelStatus for both scopes; AIWB does the same.

Field	Type	Description
status
conditions	array
imageMetadata
sourceType
aimId
discoveredProfiles
managedProfiles

AIMProfileResource

AIMProfile CRD resource (namespace- or cluster-scoped).

Cluster-scoped resources (kind AIMClusterProfile) have an empty metadata.namespace; namespace-scoped resources (kind AIMProfile) always carry it. The shape is otherwise identical, matching aim-engine’s Go types where one AIMProfileSpec/AIMProfileStatus backs both CRDs.

Field	Type	Description
metadata
spec
status

AIMProfileSpec

Spec for AIMProfile (namespace- or cluster-scoped).

Mirrors AIMProfileSpecCommon in aim-engine. Only the fields AIWB actually consumes are typed; less-used fields stay loose to preserve forward compatibility with aim-engine-side additions.

extra="allow" is required for DR-correctness: aim-engine populates additional spec fields the API does not model, and those must survive a model_validate → model_dump round-trip when the profile is mirrored to the durable S3 manifest. Pydantic v2 stores extras in __pydantic_extra__ and re-emits them under their original (camelCase) keys, which is what Kubernetes expects on apply.

Field	Type	Description
aimId	string
modelId
engine
metric
precision
type
primary
acceleratorModel
acceleratorType
acceleratorCount
image
engineArgs
engineEnv
containerEnv
modelSources
imagePullSecrets
features	array

AIMProfileStatus

Status for AIMProfile (namespace- or cluster-scoped).

Field	Type	Description
status
version
matchingNodes
hardwareSummary
resources
resolvedNodeAffinity
conditions

AIMResponse

AIMResponse API response schema.

Pure pass-through of the AIMModelResource CRD shape, which backs both cluster-scoped AIMClusterModel and namespace-scoped AIMModel resources. AIWB performs no enrichment or formatting on the response — consumers read accelerator metadata directly from status.discoveredProfiles.byHardware[] on the resource, mirroring what the aim-engine controller publishes.

Field	Type	Description
metadata
spec
status

AIMServiceAdapterRef

One adapter attached to an AIMService (spec.adapters[]).

kind + name reference an AIMArtifact in the service’s own namespace, and are the only shape aim-engine acts on today. source_uri, model_id and rank are reserved by the CRD for an inline-adapter form the engine does not read yet; CEL couples them (model_id required alongside source_uri, rank permitted only with it), so they are set together or left out entirely.

Field	Type	Description
kind	string
name	string
sourceUri
modelId
rank

AIMServiceAdapterStatus

What aim-engine reports about one attached adapter (status.adapters[]).

Passed through verbatim — AIWB neither aggregates these entries nor derives a readiness verdict from them, so the engine stays the only authority on what an adapter is doing and a state it adds later reaches consumers unchanged. name is the only field it always sets; the rest appear as the adapter progresses.

Field	Type	Description
name	string
state
adapterPath
modelId
lastError
lastObserved
loadedReplicas

AIMServiceModelRef

Reference to the AIM an AIMService deploys (spec.model).

name identifies the target AIM. It may be empty for services created by direct image reference; in that case it is populated from the resolved model (status.resolvedModel.name) once the model has been resolved.

Field	Type	Description
name

AIMServiceProfileConfig

Profile resolution config for AIMService.

Mirrors AIMServiceProfileConfig in aim-engine (ADR 006b §3). Exactly one of name (direct reference) or selector (criteria-based lookup) should be set; if both are omitted aim-engine auto-resolves the profile from spec.model.

The selector payload is kept as a loose dict so AIWB can pass the FE’s chosen criteria through unchanged. Recognized keys are metric, precision, acceleratorModel, and type (optimization tier) — aim-engine ranks matches by type (optimized > general > preview > unoptimized), primary flag, then version.

extra="allow" mirrors the rationale on AIMProfileSpec: aim-engine may introduce additional selector keys or future resolution modes that AIWB does not (yet) model, and those must survive a model_validate → model_dump round-trip so AIWB never silently drops engine-authored fields when reading and re-applying an AIMService. Pydantic v2 stores extras in __pydantic_extra__ and re-emits them under their original (camelCase) keys, which is what Kubernetes expects on apply.

Field	Type	Description
name
selector

AIMServiceRuntime

Runtime scaling status from AIMService CRD status.runtime.

Field	Type	Description
currentReplicas
desiredReplicas
minReplicas
maxReplicas
replicas

AIMServiceSpec

Field	Type	Description
model
replicas	integer	The current replicas count
routing	object
caching
runtimeConfigName
profile
profileOverrides
minReplicas		Minimum replicas for autoscaling
maxReplicas		Maximum replicas for autoscaling
autoScaling		Advanced autoscaling config
env	array
imagePullSecrets	array
adapters
adapterMode

AIMServiceStatus

Status values for AIMService resources.

CRD enum: Pending, Starting, Running, Degraded, Failed. DELETED is API-only (used by the AIM history syncer, never from K8s).

AIMServiceStatusFields

Field	Type	Description
status
routing	object
conditions	array
observedGeneration
runtime
resolvedModel
resolvedProfile
adapters

AIMVersionPolicy

Version-matching policy for custom AIMModels deriving profiles from a base.

Mirrors aim-engine’s ProfileVersionPolicy. Controls which versions of matching base profiles a custom model copies from.

• PINNED: match profiles whose status.version equals the model’s image tag.

• LATEST: match only the latest available status.version.

• ALL: match profiles at any version.

• ANY: deprecated alias of ALL, kept for backward compatibility with the CRD.

AcceleratorType

Accelerator family for AIMs (matches v1alpha2 AIMProfile spec.acceleratorType).

Lowercase to mirror aim-engine’s wire values; the API filter is case-sensitive.

AdapterMode

How an AIMService admits LoRA adapters (spec.adapterMode).

STATIC pins the service to the adapters declared at creation; DYNAMIC lets the engine load and unload them while the service runs. The CRD defaults to STATIC and makes the field immutable once set, so a deployment created without it can never move to DYNAMIC.

AdapterState

Per-adapter lifecycle state on AIMService.status.adapters[].

Mirrors the CRD enum exactly. AIWB reports these verbatim and derives nothing from them: the engine owns the progression, including whether an adapter the runtime refused (LOAD_REJECTED) is retried.

CachingConfig

AIMService caching configuration.

Replaces the deprecated boolean cacheModel field. mode controls how model weights are cached across replicas; Shared is the v1alpha2 default and matches prior cacheModel: true behavior.

env carries env vars injected only into the model-download Job, not the inference container. Use this for credentials (e.g. HF_TOKEN) that the download step needs but should not be visible to the running model server.

Field	Type	Description
mode	string
env	array

Datapoint

Field	Type	Description
value		The value of the datapoint.
timestamp	string	The timestamp of the datapoint.

DatapointMetadataBase

Field	Type	Description
label	string	The label for the series that the datapoint belongs to.

DatapointsWithMetadata

Field	Type	Description
metadata		Metadata for the datapoints.
values	array	The list of datapoints corresponding to the metadata.

DateRange

Field	Type	Description
start	string	Start of the requested time range.
end	string	End of the requested time range.

DiscoveredProfileCounts

Per-AIM accelerator/profile discovery breakdown.

aim-engine publishes this on AIMModel.status so consumers can render accelerator metadata directly from the model resource instead of joining against AIMProfile lists. The byHardware array is sorted by (acceleratorType, acceleratorModel, acceleratorCount) and has no primary flag — representative selection is the consumer’s choice.

Field	Type	Description
total
supported
unsupported
byHardware	array

FineTuningJobRequest

Input shape for POST /v1/projects/{project}/fine-tuning/jobs.

Extends FinetuneCreate by hoisting the base model identifier into the request body — the legacy endpoint passed it as a URL path parameter, but the project- scoped URL convention (EAI-5651) keeps job identity in the body.

Field	Type	Description
displayName	string	The user-visible name for the finetuning job and the resulting finetuned model. Any characters are allowed.
description		Optional human-readable description stored with the produced model or adapter.
datasetId		Deprecated UUID. Use datasetIds instead; it accepts one or more datasets.
datasetIds	array	The IDs of the datasets to use for fine-tuning. At least one dataset is required and at most 10 may be given. Mutually exclusive with the deprecated datasetId.
epochs		The number of epochs to train the model for
learningRate		The learning rate for the training process
batchSize		The batch size for the training process
hfTokenSecretName		Optional HuggingFace token secret name for downloading private models
output		What the completed job registers in the project. model produces a fine-tuned model, as it does today. adapter keeps the trained LoRA adapter instead, and is accepted only for base models whose training type is lora.
lora		LoRA hyperparameter overrides. Independent of output — these apply to any LoRA run, including one that merges into a model. Rejected for base models that train full-parameter.
baseModel		Identifier of the base model to fine-tune. Either an AIMModel UUID (for fine-tuning an existing fine-tuned model) or a HuggingFace canonical name (e.g., ‘meta-llama/Llama-3.1-8B’).

FineTuningModelsList

Paginated list of fine-tuned models in a project.

Field	Type	Description
pagination
data	array

FineTuningOutput

What a completed fine-tuning job registers in the project.

FinetunableModelResponse

Field	Type	Description
canonicalName	string	The canonical name of the finetunable model.
gpuCount		Number of GPUs required for finetuning, or null if unspecified.
compatibleAccelerators	array	AMD GPU device IDs this recipe is compatible with.
compatibleAcceleratorNames	array	Display names for the compatible AMD GPUs, resolved from cluster node labels.
hfTokenRequired	boolean	Whether this base model is gated on Hugging Face and requires a token to download. Read from the recipe overlay’s metadata.hfTokenRequired field. Defaults to true when the overlay omits it or declares a non-boolean, so a model whose gating cannot be determined is offered as gated rather than silently presented as open.
trainingType		How this base model trains. Only lora recipes can produce an adapter; a full recipe trains every weight and has no adapter to keep. A recipe that declares nothing is reported as full, matching the fine-tuning chart default.

FinetuneJobResponse

Response returned when a finetuning job is submitted.

Represents the pending job, not yet an AIMModel CR (which is created upon completion).

Field	Type	Description
workloadId	string	AIWB workload ID to track the job.
displayName	string	Name of the finetuned model to be produced.
baseModel	string	Canonical name of the base model being finetuned.
namespace	string	Namespace where the job runs.
status	string	Initial job status.

HTTPValidationError

Field	Type	Description
detail	array

InferenceCapability

Capability filter values accepted by the inference list endpoint.

Today only chat is meaningful — it narrows the list to deployments whose model is tagged for chat completions and whose serving stack is fully ready. Adding new capabilities here lets clients filter for them without endpoint proliferation.

InferenceDeployRequest

Deploy a model through the inference capability.

Currently identical to AIMDeployRequest; kept as a subclass so the inference contract can evolve independently (e.g. adding chart-based deployments) without breaking the legacy AIM route.

Field	Type	Description
adapters		Names of adapter artifacts in this project to serve alongside the base model, written to spec.adapters as AIMArtifact references. Entries must be unique, and the list is the complete set the deployment should serve. Per-adapter progress is reported on status.adapters of the deployment.
minReplicas		Minimum number of replicas for autoscaling. Requires autoScaling config.
maxReplicas		Maximum number of replicas for autoscaling. Requires autoScaling config.
autoScaling		KEDA autoscaling configuration with custom metrics. Required when using minReplicas/maxReplicas. Example: {‘metrics’: [{‘type’: ‘PodMetric’, ‘podmetric’: {‘metric’: {…}, ‘target’: {…}}}]}
model	string	Model resource name. Either an AIMClusterModel name (e.g., ‘meta-llama-3-8b’) or a namespace-scoped AIMModel name (fine-tuned model UUID). The API auto-detects which type it is.
replicas	integer	Number of replicas for this service.
imagePullSecrets		Names of the secrets for pulling AIM container images. Honored only on cluster-scoped AIMClusterModel deployments; rejected with 400 when sent for custom-onboarded/fine-tuned models.
hfToken		Hugging Face token for accessing private models (if required). Honored only on cluster-scoped AIMClusterModel deployments; rejected with 400 when sent for custom-onboarded/fine-tuned models.
metric		Profile-selector field written to spec.profile.selector.metric (latency or throughput). Ignored when profileName is set.
precision		Profile-selector field written to spec.profile.selector.precision (e.g. fp8, fp16). Ignored when profileName is set.
gpuModel		Profile-selector field written to spec.profile.selector.acceleratorModel (e.g. MI300X). Ignored when profileName is set.
gpuCount		Number of GPUs per replica. Not a profile selector — per ADR 006b §3 the selector picks profiles by hardware model. When set, written to spec.profileOverrides.acceleratorCount as a per-service override on top of the resolved profile.
engineArgs		Engine launch arguments (e.g. vLLM flags). Forwarded to AIMService.spec.profileOverrides.engineArgs.
engineEnv		Engine-process environment variables as name/value entries. Converted to AIMService.spec.profileOverrides.engineEnv.
containerEnv		Container env entries (K8s EnvVar shape). Forwarded to AIMService.spec.profileOverrides.containerEnv.
profileName		Which profile to deploy. Resolution depends on the model: for a cluster-scoped model this is a literal AIMClusterProfile name, while for a custom-onboarded model it is an identifier from that model’s profile list (a profile name, or default for the engine-provided one) which the server resolves to the profile it derives. Custom model clients therefore never handle engine-generated profile names. When unset, a custom model deploys its Default and a cluster-scoped model lets the engine resolve by aimId. Rejected with 400 for fine-tuned models, which have no selectable profiles, and when the identifier is unknown to the model or its profile is not ready.
displayName		User-visible display name for this AIM deployment. Stored as a K8s annotation; any characters are allowed.
adapterMode		How the deployment admits adapters, written to spec.adapterMode. ‘static’ serves exactly the adapters listed at deploy time; ‘dynamic’ allows adapters to be attached and detached while it runs. Immutable once deployed — a deployment created without it keeps the cluster default (‘static’) for its whole life.

InferenceDeploymentResponse

Inference deployment response.

Inherits every field of AIMServiceResponse — including the computed endpoints map. endpoints.internal is the in-cluster URL the AIWB UI uses for the chat bypass described in EAI-6310.

Field	Type	Description
metadata
spec
status
id
statusValue	string
endpoints	object

InferenceDeploymentsList

Paginated list of inference deployments.

Field	Type	Description
pagination
data	array

InferenceModelsList

Paginated list of inference base models (cluster catalog).

Field	Type	Description
pagination
data	array

InferencePatchRequest

Patch an inference deployment: its adapter set, its scaling policy, or both.

Field	Type	Description
adapters		Names of adapter artifacts in this project to serve alongside the base model, written to spec.adapters as AIMArtifact references. Entries must be unique, and the list is the complete set the deployment should serve. Per-adapter progress is reported on status.adapters of the deployment.
minReplicas		Minimum number of replicas for autoscaling. Requires autoScaling config.
maxReplicas		Maximum number of replicas for autoscaling. Requires autoScaling config.
autoScaling		KEDA autoscaling configuration with custom metrics. Required when using minReplicas/maxReplicas. Example: {‘metrics’: [{‘type’: ‘PodMetric’, ‘podmetric’: {‘metric’: {…}, ‘target’: {…}}}]}

InferenceProfilesList

Paginated list of AIMClusterProfile / AIMProfile resources.

Field	Type	Description
pagination
data	array

InferenceReplicaResponse

Kubernetes pod data for a single inference deployment replica.

Field	Type	Description
metadata
status
spec

K8sMetadata

Field	Type	Description
name	string
namespace
uid
labels	object
annotations	object
creationTimestamp
ownerReferences	array

ListResponse_FinetunableModelResponse_

Field	Type	Description
data	array	List of items

ListResponse_InferenceReplicaResponse_

Field	Type	Description
data	array	List of items

LoraSettings

LoRA hyperparameters layered over the recipe’s own values.

Only supplied fields are sent onward, so anything left unset keeps the value the recipe already uses. Unknown fields are rejected rather than ignored: a misspelled hyperparameter that trains something other than what was asked, yet still reports success, is the worst outcome for a multi-hour GPU job.

Field	Type	Description
rank		LoRA rank. Defaults to the base model recipe’s value, which is commonly 64. aim-engine advertises a maximum servable adapter rank of 32 per serving pod, so a higher rank trains successfully but may not be servable.
alpha		LoRA alpha scaling factor. Defaults to the base model recipe’s value.
dropout		LoRA dropout probability. Defaults to the base model recipe’s value.

MetricName

Supported metric names for workload-level metric retrieval.

MetricsScalar

Represents a scalar metric value at a single point in time. Used for point-in-time metrics.

Field	Type	Description
data	number	The scalar metric value.

MetricsScalarWithRange

Represents a scalar metric value aggregated over a time range. Used for metrics computed over a specified range.

Field	Type	Description
data	number	The scalar metric value.
range		The range for which the scalar metric was computed.

MetricsTimeseries

Field	Type	Description
data	array	The metrics timeseries data points.
range		The range of the timeseries.

OciMetadata

Field	Type	Description
created
description
licenses
revision
source
title
vendor
version

OptimizationMetric

Performance optimization metrics for AIM deployments.

PaginationMetadata

Pagination metadata block emitted under pagination in list responses.

totalPages is intentionally not exposed — clients derive it as ceil(total / pageSize) when needed.

Field	Type	Description
page	integer
pageSize	integer
total	integer

ProfileHardwareGroup

One accelerator footprint that an AIM can run on.

Groups by (acceleratorType, acceleratorModel, acceleratorCount) so catalog consumers can describe an AIM’s headline hardware without listing AIMProfile CRs themselves. supported reflects whether the cluster actually has nodes that satisfy this footprint.

Field	Type	Description
acceleratorType
acceleratorModel
acceleratorCount
supported	boolean
profiles	array

ProfileHardwareGroupEntry

A single (metric, precision) pair under a hardware group.

Kept loose as str | None — these are aim-engine enum values that AIWB only forwards, not switches on, so widening the engine’s enum surface here would couple AIWB to changes it doesn’t otherwise care about.

Field	Type	Description
metric
precision

ProfileOverrides

Stamp half of the derivation — identity, image, and weights overlaid onto the derived profile. For role=base derivations CEL requires aim_id and model_id (base profiles carry no identity of their own); image overrides the runtime container image and model_sources supply the BYO weights (with per-source env). Opaque onboard customProfile keys (engine, precision, etc.) pass through via extra="allow".

Field	Type	Description
aimId
modelId
image
modelSources	array

ProfileSelector

Filter half of derivedFrom — narrows which source profiles match.

extra="allow" keeps optional aim-engine filter axes we do not model (e.g. acceleratorModel, precision) round-trippable. For BYOM onboard only role + model_ref are set; per CEL, identity fields (aimId / modelId) are forbidden when role=base.

Field	Type	Description
role
modelRef

ProfileSelectorModelRef

Reference to the source AIMModel a derivation pulls profiles from.

scope is Namespace or Cluster (or Auto); for BYOM onboard it pins the derivation to a namespace-scoped base-image AIMModel.

Field	Type	Description
name	string
scope

ReplicaCondition

Field	Type	Description
type
status
reason
message

ReplicaContainer

Field	Type	Description
resources

ReplicaContainerStatus

Field	Type	Description
ready
restartCount
state

ReplicaMetadata

Field	Type	Description
name	string
creationTimestamp

ReplicaResources

Field	Type	Description
limits

ReplicaSpec

Field	Type	Description
nodeName
containers

ReplicaStatus

Field	Type	Description
phase
podIp
containerStatuses
conditions

ResolutionScope

Scope at which aim-engine resolved a reference.

CRD enum shared by status.resolvedModel / status.resolvedProfile (AIMService) and status.resolvedParent (AIMArtifact).

ResolvedRef

Reference aim-engine resolved to a concrete resource.

Mirrors aim-engine’s AIMResolvedReference: resolved_model and resolved_profile on AIMService, resolved_parent on AIMArtifact.

kind and uid are populated by AIMArtifact but not AIMService.

Field	Type	Description
name		Resolved resource name
namespace		Namespace when namespace-scoped
scope		Scope the reference resolved at
kind		Kind of the resolved reference, when known
uid		Unique identifier of the resolved reference, when known

TimeseriesRange

Field	Type	Description
start	string	Start of the requested time range.
end	string	End of the requested time range.
intervalSeconds	integer	The interval in seconds for the timeseries data.
timestamps	array	The keys for the datapoints in the timeseries.

TrainingType

How a fine-tuning recipe trains, fixed by the base model’s recipe rather than the caller.

ValidationError

Field	Type	Description
loc	array
msg	string
type	string
input
ctx	object

Related

• Keycloak Authentication

• Session Lifetime

• API Keys for Programmatic Access

• Swagger UI documentation

• OpenAPI Specification