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, list and inspect deployments, adjust scaling, inspect replicas and metrics, and undeploy.

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

Limitations

• LoRA fine-tuning is not part of this API version. Only full fine-tuning workflows are exposed by the public contract.

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 model). The API auto-detects which type it is.

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.

422

Invalid scaling policy (e.g., missing one of minReplicas/maxReplicas/autoScaling, or maxReplicas < minReplicas).

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.

422

Validation Error

HTTPValidationError

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

Update an inference deployment

Update an inference deployment without redeploying the model.

Currently the only supported change is the scaling policy. All three scaling fields (minReplicas, maxReplicas, autoScaling) must be provided together.

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

All scaling fields are absent (none of minReplicas, maxReplicas, autoScaling provided).

422

Scaling fields are partially provided (e.g., autoScaling missing while min/max set) or maxReplicas < minReplicas.

502

Kubernetes patch on the AIMService failed.

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.

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.

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.

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.

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. datasetId must reference a dataset already uploaded into the same project — datasets from other projects are not visible. An optional displayName query parameter sets the user-facing label on the resulting workload.

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

AIMImageMetadata

Field	Type	Description
model
oci
originalLabels	object

AIMModelCondition

A single status condition on an AIMModel.

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

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

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

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

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

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	object
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

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

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.

AcceleratorType

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

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

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.
datasetId	string	The ID of the dataset to be used for finetuning
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
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

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		Whether this base model is gated on Hugging Face and requires a token to download. Read from the recipe overlay’s top-level hfTokenRequired field. Null when the overlay does not declare it.

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
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		Explicit AIMProfile/AIMClusterProfile name. When set, spec.profile.name is written. When unset, the engine resolves the profile via the model’s aimId. Rejected with 400 when sent for fine-tuned models.
displayName		User-visible display name for this AIM deployment. Stored as a K8s annotation; any characters are allowed.

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
clusterAuthGroupId		Extract cluster-auth group ID from routing annotations.

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 (scaling policy).

Field	Type	Description
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

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

ResolvedRef

Resolved reference (model/profile/template name).

Mirrors aim-engine’s AIMResolvedReference (Go type). Used for both resolved_model and resolved_profile. Consumers that need accelerator/precision/metric details join against the AIMClusterProfile / AIMProfile catalog via the /inference/profiles and /projects/{project}/profiles endpoints.

scope distinguishes cluster- vs namespace-scoped resolutions so the UI can target the right endpoint without probing both.

Field	Type	Description
name		Resolved resource name
namespace		Namespace when namespace-scoped
scope		Resolution scope — ‘Namespace’, ‘Cluster’, ‘Merged’, or ‘Unknown’
kind		Fully-qualified 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.

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