API Reference

July 20, 2026 · View on GitHub

Complete reference for using the AICR API Server.

Overview

The AICR API Server provides HTTP REST access to recipe generation and bundle creation for GPU-accelerated infrastructure. Use the API for programmatic access to configuration recommendations and deployment artifacts.

Version numbers in the sample requests and responses below (server version, chart versions, driver versions) are illustrative. The authoritative, current versions are in the Component Catalog and the Container Images BOM.

┌──────────────┐      ┌──────────────┐
│ GET /recipe  │─────▶│   Recipe     │
└──────────────┘      └──────────────┘
        │
        ▼
┌──────────────┐      ┌──────────────┐
│ POST /bundle │─────▶│  bundles.zip │
└──────────────┘      └──────────────┘

API vs CLI

  • Use the API for remote recipe generation and bundle creation
  • Use the CLI for local operations, snapshot capture, and ConfigMap integration
FeatureAPICLI
Recipe generation✅ GET /v1/recipe✅ aicr recipe
Value query✅ GET /v1/query✅ aicr query
Bundle creation✅ POST /v1/bundle✅ aicr bundle
Snapshot capture❌ Use CLI✅ aicr snapshot
ConfigMap I/O❌ Use CLI✅ cm:// URIs
Agent deployment❌ Use CLI✅ aicr snapshot

Base URL

Local development (example):

http://localhost:8080

Start the local server:

docker pull ghcr.io/nvidia/aicrd:latest
docker run -p 8080:8080 ghcr.io/nvidia/aicrd:latest

Quick Start

Get a Recipe

Generate an optimized configuration recipe for your environment:

# GET: Basic recipe for H100 on EKS (query parameters)
curl "http://localhost:8080/v1/recipe?accelerator=h100&service=eks"

# GET: Training workload on Ubuntu
curl "http://localhost:8080/v1/recipe?accelerator=h100&service=eks&intent=training&os=ubuntu"

# POST: Recipe from criteria file (YAML body)
curl -X POST "http://localhost:8080/v1/recipe" \
  -H "Content-Type: application/x-yaml" \
  -d 'kind: RecipeCriteria
apiVersion: aicr.run/v1alpha2
metadata:
  name: my-config
spec:
  service: eks
  accelerator: h100
  intent: training'

# Save recipe to file
curl -s "http://localhost:8080/v1/recipe?accelerator=h100&service=eks" -o recipe.json

Generate Bundles

Create deployment bundles from a recipe:

# Pipe recipe directly to bundle endpoint.
# The POST body must be a fully-hydrated RecipeResult; piping GET /v1/recipe
# output (as below) supplies one. Do not hand-author a partial body.
curl -s "http://localhost:8080/v1/recipe?accelerator=h100&service=eks" | \
  curl -X POST "http://localhost:8080/v1/bundle" \
    -H "Content-Type: application/json" -d @- -o bundles.zip

# Extract the bundles
unzip bundles.zip -d ./bundles

# Verify the complete extracted inventory before deployment
(cd ./bundles && aicr verify .)

Endpoints

GET /

Service information and available routes.

curl "http://localhost:8080/"

Response:

{
  "service": "aicrd",
  "version": "v0.14.0",
  "routes": ["/v1/recipe", "/v1/query", "/v1/bundle"]
}

GET /v1/recipe

Generate an optimized configuration recipe based on environment parameters.

Query Parameters:

ParameterTypeDefaultDescription
servicestringanyK8s service: eks, gke, aks, oke, ocp, kind, lke, bcm, any
acceleratorstringanyGPU type: h100, h200, gb200, b200, a100, l40, l40s, rtx-pro-6000, any
gpustringanyAlias for accelerator
intentstringanyWorkload: training, inference, any
osstringanyNode OS: ubuntu, rhel, cos, amazonlinux, ol, talos, any
platformstringanyPlatform/framework: dynamo, kubeflow, nim, runai, slurm, any
nodesinteger0GPU node count (0 = any)

Examples:

# Minimal request
curl "http://localhost:8080/v1/recipe"

# Specify accelerator
curl "http://localhost:8080/v1/recipe?accelerator=h100"

# Full specification
curl "http://localhost:8080/v1/recipe?service=eks&accelerator=h100&intent=training&os=ubuntu&nodes=8"

# Using gpu alias (os is required here: gb200 on gke has no OS-agnostic recipe)
curl "http://localhost:8080/v1/recipe?gpu=gb200&service=gke&os=cos"

# Pretty print with jq
curl -s "http://localhost:8080/v1/recipe?accelerator=h100" | jq '.'

POST /v1/recipe

Generate an optimized configuration recipe from a criteria file body. This endpoint provides an alternative to query parameters, accepting a Kubernetes-style RecipeCriteria resource in the request body.

Content Types:

  • application/json - JSON format
  • application/x-yaml - YAML format

Request Body:

The request body must be a RecipeCriteria resource:

kind: RecipeCriteria
apiVersion: aicr.run/v1alpha2
metadata:
  name: my-criteria
spec:
  service: eks
  accelerator: gb200
  os: ubuntu
  intent: training
  platform: kubeflow
  nodes: 8

Examples:

# POST with YAML body
curl -X POST "http://localhost:8080/v1/recipe" \
  -H "Content-Type: application/x-yaml" \
  -d 'kind: RecipeCriteria
apiVersion: aicr.run/v1alpha2
metadata:
  name: training-config
spec:
  service: eks
  accelerator: h100
  intent: training'

# POST with JSON body
curl -X POST "http://localhost:8080/v1/recipe" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "RecipeCriteria",
    "apiVersion": "aicr.run/v1alpha2",
    "metadata": {"name": "training-config"},
    "spec": {
      "service": "eks",
      "accelerator": "h100",
      "intent": "training"
    }
  }'

# POST with criteria file
curl -X POST "http://localhost:8080/v1/recipe" \
  -H "Content-Type: application/yaml" \
  -d @criteria.yaml

# Pretty print response
curl -s -X POST "http://localhost:8080/v1/recipe" \
  -H "Content-Type: application/json" \
  -d '{"kind":"RecipeCriteria","apiVersion":"aicr.run/v1alpha2","spec":{"service":"eks","accelerator":"h100"}}' \
  | jq '.'

Error Responses:

  • 400 Bad Request - Invalid criteria format, missing required fields, or invalid enum values
  • 400 Bad Request - A stated criteria dimension is not honored by any applicable recipe overlay (uncovered dimension). This applies to both GET /v1/recipe and POST /v1/recipe: every dimension you state (service, accelerator, intent, os, platform) must be matched by at least one applied overlay, or the request fails instead of silently returning a recipe that ignores it. nodes is exempt — it is advisory and never required to be covered. The response's details.uncovered array names the offending dimension(s), the requested value, and any validCompletions (additional criteria that would make the request coverable). Snapshot-driven resolution (CLI --snapshot / Go SDK) may additionally attach excludedOverlays and constraintWarnings to the error; the HTTP API resolves from criteria only and never emits those two fields.
  • 405 Method Not Allowed - Only GET and POST are supported

Uncovered-Dimension Error Example:

{
  "code": "INVALID_REQUEST",
  "message": "platform 'kubeflow' for criteria(service=eks, accelerator=h100, intent=training, platform=kubeflow) requires os (valid: ubuntu)",
  "details": {
    "uncovered": [
      {
        "dimension": "platform",
        "requestedValue": "kubeflow",
        "validCompletions": [{"os": "ubuntu"}]
      }
    ]
  },
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:00Z",
  "retryable": false
}

Response:

{
  "apiVersion": "aicr.run/v1alpha2",
  "kind": "RecipeResult",
  "metadata": {
    "version": "v0.14.0",
    "appliedOverlays": [
      "base",
      "eks",
      "eks-training",
      "gb200-eks-training"
    ],
    "excludedOverlays": [
      {
        "name": "h100-eks-ubuntu-training",
        "reason": "mixin-constraint-failed"
      }
    ],
    "constraintWarnings": [
      {
        "overlay": "h100-eks-ubuntu-training",
        "constraint": "OS.sysctl./proc/sys/kernel/osrelease",
        "expected": ">= 6.8",
        "actual": "5.15.0",
        "reason": "mixin-constraint-failed: expected >= 6.8, got 5.15.0"
      }
    ]
  },
  "criteria": {
    "service": "eks",
    "accelerator": "gb200",
    "intent": "training",
    "os": "any",
    "platform": "any"
  },
  "constraints": [
    {
      "name": "GPU.driver.version",
      "value": "580.82.07"
    },
    {
      "name": "GPU.driver.cudaVersion",
      "value": "13.1"
    }
  ],
  "componentRefs": [
    {
      "name": "gpu-operator",
      "type": "Helm",
      "chart": "gpu-operator",
      "source": "https://helm.ngc.nvidia.com/nvidia",
      "version": "v25.3.3"
    },
    {
      "name": "network-operator",
      "type": "Helm",
      "chart": "network-operator",
      "source": "https://helm.ngc.nvidia.com/nvidia",
      "version": "v25.4.0"
    }
  ],
  "deploymentOrder": [
    "gpu-operator",
    "network-operator"
  ]
}

metadata.excludedOverlays is optional. When present, each entry includes the overlay name and a machine-readable reason such as constraint-failed or mixin-constraint-failed.

GET /v1/query

Query a specific value from a fully hydrated recipe. Resolves a recipe from criteria (same parameters as GET /v1/recipe), merges all base, overlay, and inline overrides, then returns the value at the given selector path.

Query Parameters:

All GET /v1/recipe parameters are supported, plus:

ParameterTypeRequiredDescription
selectorstringYesDot-delimited path to the value to extract (e.g. components.gpu-operator.values.driver.version). Empty string returns the entire hydrated recipe.

Response:

  • Scalar values (string, number, bool) are returned as plain JSON values
  • Complex values (maps, lists) are returned as JSON objects/arrays

Error Responses:

GET /v1/query and POST /v1/query resolve a recipe through the same engine as /v1/recipe, so a stated criteria dimension not honored by any applicable overlay fails the same way: 400 Bad Request with the details.uncovered array described in the POST /v1/recipe error responses above.

Examples:

# Get a specific Helm value
curl -s "http://localhost:8080/v1/query?service=eks&accelerator=h100&intent=training&selector=components.gpu-operator.values.driver.version"

# Get deployment order
curl -s "http://localhost:8080/v1/query?service=eks&accelerator=h100&intent=training&selector=deploymentOrder" | jq '.'

# Get a component subtree
curl -s "http://localhost:8080/v1/query?service=eks&accelerator=h100&selector=components.gpu-operator.values.driver" | jq '.'

POST /v1/query

Alternative to GET /v1/query that accepts the criteria and selector in the request body. The body is a QueryRequest with a criteria object (same fields as the RecipeCriteria spec) and a selector string.

Content Types:

  • application/json - JSON format
  • application/x-yaml - YAML format

Request Body:

criteria:
  service: eks
  accelerator: h100
  intent: training
selector: "components.gpu-operator.values.driver.version"

Examples:

curl -X POST "http://localhost:8080/v1/query" \
  -H "Content-Type: application/json" \
  -d '{
    "criteria": {"service": "eks", "accelerator": "h100", "intent": "training"},
    "selector": "components.gpu-operator.values.driver.version"
  }'

The response format matches GET /v1/query: scalar values are returned as plain JSON values; maps and lists are returned as JSON objects/arrays.

POST /v1/bundle

Generate deployment bundles from a recipe.

Query Parameters:

ParameterTypeDefaultDescription
bundlersstring(all)Comma-delimited list of recipe component names to bundle (e.g. gpu-operator,network-operator). Whitespace around names is trimmed. Components not listed are skipped as if disabled (their dependency edges are treated as satisfied externally). A name the recipe does not declare, or one that is disabled (by the recipe or a set enabled=false override), is rejected with HTTP 400.
setstring[]Value overrides (format: bundler:path.to.field=value). Repeat for multiple. The reserved prefix deployer: carries Argo CD Application options for deployer=argocd and deployer=argocd-helm (namePrefix, destinationServer, project, cascadeDelete), e.g. set=deployer:namePrefix=tenant-a-. Unknown deployer: keys — or the prefix with any other deployer — are rejected with HTTP 400. See the CLI reference's Argo CD Deployer Options for full semantics.
dynamicstring[]Declare value paths as install-time parameters (format: component:path.to.field). Repeat for multiple. Supported with deployer=helm, deployer=argocd-helm, deployer=flux, and deployer=helmfile.
system-node-selectorstring[]Node selectors for system components (format: key=value). Repeat for multiple.
system-node-tolerationstring[]Tolerations for system components (format: key=value:effect). Repeat for multiple.
accelerated-node-selectorstring[]Node selectors for GPU nodes (format: key=value). Repeat for multiple.
accelerated-node-tolerationstring[]Tolerations for GPU nodes (format: key=value:effect). Repeat for multiple.
nodesint0Estimated number of GPU nodes (0 = unset). Written to Helm value paths declared in the registry under nodeScheduling.nodeCountPaths.
vendor-chartsboolfalsePull upstream Helm chart bytes into the bundle at bundle time so the artifact is fully self-contained and air-gap deployable. Each vendored chart is recorded in provenance.yaml with name, version, source URL, and SHA256. Trades the upstream CVE-yank fail-loud signal for offline deployability — see the CLI reference's "Vendoring Charts for Air-Gap" section for the full tradeoff. Requires the helm binary on the API server's $PATH and registry credentials configured for any private upstream repos (HELM_REPOSITORY_USERNAME/HELM_REPOSITORY_PASSWORD for HTTP(S); docker config for OCI). If prerequisites are missing the request fails with a structured error code (SERVICE_UNAVAILABLE / HTTP 503 for missing helm, UNAUTHORIZED / HTTP 401 for credentials).
serialboolfalseSequence components strictly one at a time in deployment order, disabling the parallel rollout of independent components. Affects deployer=argocd, argocd-helm, flux, and helmfile (helm is already serial): argocd falls back to a linear sync-wave per folder, flux chains each HelmRelease dependsOn to the previous component, and helmfile chains every release via needs: into one linear apply order. An escape hatch for reproducing the pre-parallelism ordering or bisecting a rollout.
deployerstringhelmDeployment method: helm, argocd, argocd-helm, flux, or helmfile
repostringGit repository URL for GitOps deployments (used with deployer=argocd and deployer=flux; ignored by deployer=argocd-helm)
app-namestringParent Argo Application name (default: aicr-stack for deployer=argocd-helm, nvidia-stack for deployer=argocd). Must be a DNS-1123 subdomain. Required when deploying multiple non-overlapping AICR bundles to the same Argo CD namespace so the parent Applications do not collide. For deployer=argocd-helm, the value is the chart default and can still be overridden at install time via helm install --set appName=.... Rejected with HTTP 400 on other deployers.

Request Body:

The request body is the recipe (RecipeResult) directly. No wrapper object needed.

Components

These are the recipe components in recipes/registry.yaml — the names the bundlers query parameter accepts (a request may only name components the recipe declares). The registry is the authoritative source — see the component catalog for the full, current list with detailed descriptions. The table below is illustrative of commonly used components:

ComponentDescription
agentgatewayKubernetes Gateway API implementation for AI/ML inference (InferencePool routing)
agentgateway-crdsKubernetes Gateway API CRDs for AI/ML inference (Gateway API + Inference Extension)
aws-ebs-csi-driverAmazon EBS CSI driver (EKS)
aws-efaAWS Elastic Fabric Adapter device plugin (EKS)
cert-managerTLS certificate management
dynamo-platformNVIDIA Dynamo inference serving platform
gatekeeperOPA Gatekeeper policy controller
gke-nccl-tcpxoNCCL TCPxO network plugin for optimized collective communication (GKE)
gpu-operatorNVIDIA GPU Operator — driver and runtime lifecycle
gpu-operator-ocpGPU Operator variant for OpenShift (OCP)
gpu-operator-ocp-olmGPU Operator for OpenShift via Operator Lifecycle Manager (OLM)
groveDynamo pod lifecycle management
k8s-ephemeral-storage-metricsEphemeral storage usage metrics
k8s-nim-operatorNVIDIA NIM Operator for inference microservice deployments
kai-schedulerDRA-aware gang scheduler with topology-aware placement
kube-prometheus-stackPrometheus, Grafana, Alertmanager monitoring stack
kubeflow-trainerKubeflow Training Operator for distributed training
kueueKubernetes-native job queuing for batch and AI workloads
network-operatorNVIDIA Network Operator — RDMA, SR-IOV, host networking
network-operator-ocpNetwork Operator variant for OpenShift (OCP)
network-operator-ocp-olmNetwork Operator for OpenShift via Operator Lifecycle Manager (OLM)
nfdNode Feature Discovery — labels nodes with hardware features; publishes per-node NodeResourceTopology CRDs on production GPU recipes
nfd-ocpNode Feature Discovery variant for OpenShift (OCP)
nfd-ocp-olmNode Feature Discovery for OpenShift via Operator Lifecycle Manager (OLM)
nodewright-customizationsEnvironment-specific node tuning profiles
nodewright-operatorOS-level node tuning and kernel configuration
nvidia-dra-driver-gpuDynamic Resource Allocation driver for GPUs
nvsentinelGPU health monitoring and automated remediation
prometheus-adapterCustom metrics for HPA scaling
prometheus-operator-crdsCRDs for the prometheus-operator (Alertmanager, Prometheus, ServiceMonitor, etc.)
slinky-slurmSlinky-managed Slurm cluster instance (Controller, LoginSet, NodeSet, RestApi); reconciled by slinky-slurm-operator
slinky-slurm-operatorSchedMD Slinky Slurm operator and admission webhook
slinky-slurm-operator-crdsCRDs for the SchedMD Slinky Slurm operator (slinky.slurm.net)

Examples:

Note: The POST body must be a fully-hydrated RecipeResult — the server adopts the body as-is and does not hydrate registry defaults, so a hand-authored partial body (missing namespace, valuesFile, overrides, dependencyRefs) yields empty values and namespaces in the generated bundle. Obtain a complete body from aicr recipe ... --format json --output - (the CLI defaults to YAML, but POST /v1/bundle JSON-decodes its body) or GET /v1/recipe and pass it unchanged. The inline bodies below are elided for brevity (only a few component fields shown) — use a generated RecipeResult, not these literals.

To bundle a subset of the recipe's components, use the bundlers query parameter (e.g. ?bundlers=gpu-operator,network-operator) rather than hand-trimming componentRefs — trimming the body silently drops required dependencies and breaks deployers like Helmfile on dangling dependencyRefs. The filter prunes those edges safely (a filtered-out dependency is assumed satisfied externally) and rejects unknown or disabled component names with HTTP 400.

Enabled Helm refs must reference a deployable primary: an external chart (a source repository plus an effective version — empty, whitespace-only, or a bare v is rejected; the chart name falls back to the component name when chart is unset, but a chart without a source is rejected) or local primary manifestFiles. chart, source, and version values carrying surrounding whitespace are rejected — deployers consume them verbatim. Incoherent refs are rejected with HTTP 400 naming the component.

# Basic: pipe recipe to bundle
curl -s "http://localhost:8080/v1/recipe?accelerator=h100&service=eks" | \
  curl -X POST "http://localhost:8080/v1/bundle" \
    -H "Content-Type: application/json" -d @- -o bundles.zip

# Advanced: with value overrides and Argo CD deployer
curl -s "http://localhost:8080/v1/recipe?accelerator=h100&service=eks" | \
  curl -X POST "http://localhost:8080/v1/bundle?deployer=argocd&repo=https://github.com/my-org/my-gitops-repo.git&set=gpuoperator:gds.enabled=true" \
    -H "Content-Type: application/json" -d @- -o bundles.zip

# With node scheduling for system and GPU nodes
# (recipe.json must be a fully-hydrated RecipeResult, e.g. from GET /v1/recipe)
curl -X POST "http://localhost:8080/v1/bundle?system-node-selector=nodeGroup=system&system-node-toleration=dedicated=system:NoSchedule&accelerated-node-selector=nvidia.com/gpu.present=true&accelerated-node-toleration=nvidia.com/gpu=present:NoSchedule" \
  -H "Content-Type: application/json" \
  -d @recipe.json \
  -o bundles.zip

# Generate bundles from a saved (fully-hydrated) recipe
curl -X POST "http://localhost:8080/v1/bundle" \
  -H "Content-Type: application/json" \
  -d @recipe.json \
  -o bundles.zip

# Elided literal body (NOT complete — use a generated RecipeResult instead)
curl -X POST "http://localhost:8080/v1/bundle" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "aicr.run/v1alpha2",
    "kind": "RecipeResult",
    "componentRefs": [
      {"name": "gpu-operator", "type": "Helm", "chart": "gpu-operator", "source": "https://helm.ngc.nvidia.com/nvidia", "version": "v26.3.2", "namespace": "gpu-operator", "valuesFile": "components/gpu-operator/values.yaml"},
      {"name": "network-operator", "type": "Helm", "chart": "network-operator", "source": "https://helm.ngc.nvidia.com/nvidia", "version": "26.1.1", "namespace": "nvidia-network-operator", "valuesFile": "components/network-operator/values.yaml"}
    ],
    "deploymentOrder": ["gpu-operator", "network-operator"]
  }' \
  -o bundles.zip

Response Headers:

HeaderDescriptionExample
Content-TypeAlways application/zipapplication/zip
Content-DispositionDownload filenameattachment; filename="bundles.zip"
X-Bundle-FilesNumber of verified regular files streamed into the archive10
X-Bundle-SizeAggregate uncompressed bytes of those verified regular files45678
X-Bundle-DurationGeneration time1.234s

Before writing the response, the server stages a private, revalidated closed-world inventory. The ZIP contains only the inventory-derived directories and regular files, including recipe.yaml when present; unverified entries are rejected rather than archived. X-Bundle-Files and X-Bundle-Size are derived from that same frozen inventory.

Bundle Structure

bundles.zip
├── deploy.sh                    # root automation script (executable)
├── README.md                    # root deployment guide
├── checksums.txt                # SHA256 for every regular payload file in the archive
├── recipe.yaml                  # canonical post-resolution recipe (helm deployer)
├── 001-<component>/             # per-component folder (NNN-prefixed)
│   ├── install.sh               # component install script
│   ├── values.yaml              # static Helm values
│   ├── cluster-values.yaml      # per-cluster dynamic values
│   └── upstream.env             # CHART/REPO/VERSION (upstream-helm only)
└── 002-<component>/
    ├── install.sh
    ├── values.yaml
    └── cluster-values.yaml

Checksums are root-level only; component folders carry install.sh at their root (no scripts/ subdirectory), and no uninstall.sh/undeploy.sh is generated. After extraction, aicr verify . performs full closed-world verification: every manifest digest must match and every additional file or directory, symlink, or other non-regular object is rejected, except the exact allowed inventory metadata paths.

GET /health

Service health check (liveness probe).

curl "http://localhost:8080/health"

Response:

{
  "status": "healthy",
  "timestamp": "2026-01-11T10:30:00Z"
}

GET /ready

Service readiness check (readiness probe).

curl "http://localhost:8080/ready"

Response:

{
  "status": "ready",
  "timestamp": "2026-01-11T10:30:00Z"
}

GET /metrics

Prometheus metrics endpoint.

curl "http://localhost:8080/metrics"

Key Metrics:

MetricTypeDescription
aicr_http_requests_totalcounterTotal HTTP requests by method, path, status
aicr_http_request_duration_secondshistogramRequest latency distribution
aicr_http_requests_in_flightgaugeCurrent concurrent requests
aicr_rate_limit_rejects_totalcounterRate limit rejections

Complete Workflow Example

Fetch a recipe and generate bundles in one workflow:

#!/bin/bash

# Step 1: Get recipe for H100 on EKS for training
echo "Fetching recipe..."
curl -s "http://localhost:8080/v1/recipe?accelerator=h100&service=eks&intent=training" \
  -o recipe.json

# Display recipe summary
echo "Recipe components:"
jq -r '.componentRefs[] | "  - \(.name): \(.version)"' recipe.json

# Step 2: Generate bundles from recipe (pipe directly)
# recipe.json is the fully-hydrated RecipeResult fetched in Step 1.
echo "Generating bundles..."
curl -s -X POST "http://localhost:8080/v1/bundle" \
  -H "Content-Type: application/json" \
  -d @recipe.json \
  -o bundles.zip

# Alternative: one-liner without intermediate file
# curl -s "http://localhost:8080/v1/recipe?accelerator=h100&service=eks" | \
#   curl -X POST "http://localhost:8080/v1/bundle" \
#     -H "Content-Type: application/json" -d @- -o bundles.zip

# Step 3: Extract and verify
echo "Extracting bundles..."
unzip -q bundles.zip -d ./deployment

# Verify the complete inventory (checksums.txt is at the bundle root)
echo "Verifying bundle inventory..."
cd deployment
aicr verify .

# Step 4: Deploy (example)
echo "Bundle ready for deployment:"
ls -la

Error Handling

Error Response Format

{
  "code": "ERROR_CODE",
  "message": "Human-readable error description",
  "details": { ... },
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-01-11T10:30:00Z",
  "retryable": true
}

Error Codes

CodeHTTP StatusDescriptionRetryable
INVALID_REQUEST400Invalid query parameters, request body, or disallowed criteria valueNo
UNAUTHORIZED401Authentication or authorization failureNo
NOT_FOUND404Selector path not found in the resolved configurationNo
METHOD_NOT_ALLOWED405Wrong HTTP methodNo
CONFLICT409Resource state conflict (e.g., already exists or version mismatch)No
RATE_LIMIT_EXCEEDED429Too many requestsYes
INTERNAL500Server errorYes
SERVICE_UNAVAILABLE503Server temporarily unavailableYes
TIMEOUT504Operation exceeded its time limitYes

INVALID_REQUEST is not always 400: POST /v1/query and POST /v1/recipe return it with HTTP 413 Request Entity Too Large when the request body exceeds the server's body-size limit (MaxRecipePOSTBytes).

Handling Rate Limits

# Check rate limit headers
curl -I "http://localhost:8080/v1/recipe?accelerator=h100"

# Response headers:
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 95
# X-RateLimit-Reset: 1736589000

When rate limited (HTTP 429), use the Retry-After header:

# Retry with backoff
response=$(curl -s -w "%{http_code}" "http://localhost:8080/v1/recipe?accelerator=h100")
if [ "${response: -3}" = "429" ]; then
  retry_after=$(curl -sI "http://localhost:8080/v1/recipe" | grep -i "Retry-After" | awk '{print \$2}')
  echo "Rate limited. Retrying after ${retry_after}s..."
  sleep "$retry_after"
fi

Rate Limiting

  • Limit: 100 requests per second (a single process-global token bucket shared across all clients, not per-IP)
  • Burst: 200 requests
  • Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
  • 429 Response: Includes Retry-After header

Criteria Allowlists

The API server can be configured to restrict which criteria values are allowed. This enables operators to limit the API to specific accelerators, services, intents, or OS types.

Configuration

Allowlists are configured via environment variables when starting the server:

Environment VariableDescriptionExample
AICR_ALLOWED_ACCELERATORSComma-separated list of allowed GPU typesh100,l40
AICR_ALLOWED_SERVICESComma-separated list of allowed K8s serviceseks,gke
AICR_ALLOWED_INTENTSComma-separated list of allowed workload intentstraining
AICR_ALLOWED_OSComma-separated list of allowed OS typesubuntu,rhel

Behavior:

  • If an environment variable is not set, all values for that criteria are allowed
  • If an environment variable is set, only the specified values are permitted
  • The any value is always allowed regardless of allowlist configuration
  • Allowlists apply to both /v1/recipe and /v1/bundle endpoints

Example Configuration

# Start server allowing only H100 and L40 GPUs on EKS
docker run -p 8080:8080 \
  -e AICR_ALLOWED_ACCELERATORS=h100,l40 \
  -e AICR_ALLOWED_SERVICES=eks \
  ghcr.io/nvidia/aicrd:latest

Error Response

When a disallowed criteria value is requested:

curl "http://localhost:8080/v1/recipe?accelerator=gb200&service=eks"

Response (HTTP 400):

{
  "code": "INVALID_REQUEST",
  "message": "accelerator type not allowed",
  "details": {
    "requested": "gb200",
    "allowed": ["h100", "l40"]
  },
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-01-27T10:30:00Z",
  "retryable": false
}

CLI Behavior

The CLI (aicr) is not affected by allowlists. Allowlists only apply to the API server, allowing operators to restrict API access while maintaining full CLI functionality for administrative tasks.

Programming Language Examples

Python

import requests
import zipfile
import io

BASE_URL = "http://localhost:8080"

# Get recipe
params = {
    "accelerator": "h100",
    "service": "eks",
    "intent": "training",
    "os": "ubuntu"
}

resp = requests.get(f"{BASE_URL}/v1/recipe", params=params)
resp.raise_for_status()
recipe = resp.json()

print(f"Recipe has {len(recipe['componentRefs'])} components")

# Generate bundles — the (fully-hydrated) recipe is the request body.
resp = requests.post(
    f"{BASE_URL}/v1/bundle",
    json=recipe,
)
resp.raise_for_status()

# Extract zip
with zipfile.ZipFile(io.BytesIO(resp.content)) as zf:
    zf.extractall("./deployment")
    print(f"Extracted {len(zf.namelist())} files")

Go

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
)

func main() {
    baseURL := "http://localhost:8080"

    // Get recipe
    params := url.Values{}
    params.Add("accelerator", "h100")
    params.Add("service", "eks")
    
    resp, err := http.Get(baseURL + "/v1/recipe?" + params.Encode())
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var recipe map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&recipe)
    
    fmt.Printf("Got recipe with %d components\n", 
        len(recipe["componentRefs"].([]interface{})))
}

JavaScript/Node.js

const BASE_URL = "http://localhost:8080";

async function main() {
    // Get recipe
    const params = new URLSearchParams({
        accelerator: "h100",
        service: "eks",
        intent: "training"
    });
    
    const recipeResp = await fetch(`${BASE_URL}/v1/recipe?${params}`);
    const recipe = await recipeResp.json();
    
    console.log(`Recipe has ${recipe.componentRefs.length} components`);
    
    // Generate bundles — the (fully-hydrated) recipe is the request body.
    const bundleResp = await fetch(`${BASE_URL}/v1/bundle`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(recipe),
    });
    
    // Save zip
    const buffer = await bundleResp.arrayBuffer();
    require("fs").writeFileSync("bundles.zip", Buffer.from(buffer));
    console.log("Bundles saved to bundles.zip");
}

main();

Shell Script (Batch Processing)

#!/bin/bash
# Generate recipes for multiple environments

environments=(
  "os=ubuntu&accelerator=h100&service=eks"
  "os=ubuntu&accelerator=gb200&service=gke"
  "os=rhel&accelerator=a100&service=aks"
)

for env in "${environments[@]}"; do
  echo "Fetching recipe for: $env"

  curl -s "http://localhost:8080/v1/recipe?${env}" \
    | jq -r '.componentRefs[] | "\(.name): \(.version)"'

  echo ""
done

OpenAPI Specification

The full OpenAPI 3.1 specification is available at: api/aicr/v1/server.yaml

Generate client SDKs:

# Download spec
curl https://raw.githubusercontent.com/NVIDIA/aicr/main/api/aicr/v1/server.yaml \
  -o openapi.yaml

# Generate Python client
openapi-generator-cli generate -i openapi.yaml -g python -o ./python-client

# Generate Go client
openapi-generator-cli generate -i openapi.yaml -g go -o ./go-client

# Generate TypeScript client
openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./ts-client

Troubleshooting

Common Issues

"Invalid accelerator type" error:

# Use valid values: h100, h200, gb200, b200, a100, l40, l40s, rtx-pro-6000, any
curl "http://localhost:8080/v1/recipe?accelerator=h100"

"Recipe is required" error:

# The body IS the RecipeResult itself — not wrapped in a {"recipe": ...} field.
# Pass a fully-hydrated RecipeResult (e.g. from GET /v1/recipe) directly:
curl -s "http://localhost:8080/v1/recipe?accelerator=h100&service=eks" | \
  curl -X POST "http://localhost:8080/v1/bundle" \
    -H "Content-Type: application/json" -d @- -o bundles.zip

Empty zip file:

# Check recipe has componentRefs
curl -s "http://localhost:8080/v1/recipe?accelerator=h100" | jq '.componentRefs'

Connection refused (local):

# Start local server first
make server

See Also