# Overview
URL: https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/overview.html

> Core concepts, object model, and design principles.

# Overview

The Workload API provides a unified compute abstraction for running AI workloads on DataRobot. This page explains the core architecture, object model, and how the different components work together.

## Core concepts

The Workload API uses a layered abstraction that separates what you want to run from how it runs. This design lets you iterate quickly during development while keeping governance and versioning controls for production.

### Object hierarchy

The API is built around four primary objects:

| Object | Description |
| --- | --- |
| Artifacts | Define your business logic—container images, runtime configuration, and metadata that describe your application, model, or agent. Artifacts focus on what you're building, not how it scales or where it runs. |
| Workloads | Running instances of artifacts. When you start an artifact, the system creates a workload that manages the underlying compute resources, handles scaling, and tracks lifecycle state. |
| Deployments | Stable, governed endpoints for production workloads. A deployment wraps a workload with a consistent URL, health monitoring, access controls, and audit logging. |
| Artifact collections | Maintain version history. When you register an artifact for production use, it becomes part of a collection that tracks all versions of that artifact over time. |

## Artifact lifecycle

Artifacts exist in two states that reflect different stages of the development workflow.

### Draft artifacts

Draft artifacts are designed for experimentation. They are mutable, unversioned, and can be updated freely as you iterate on your implementation. Use draft artifacts when you're actively developing and testing.

A draft artifact:

- Can be modified in place
- Does not belong to a version collection
- Cannot be attached to a deployment
- Is intended for development and testing workflows

### Registered artifacts

Registered artifacts are immutable snapshots intended for production. When you register an artifact, the system assigns it a version number and adds it to an artifact collection.

A registered artifact:

- Is immutable once created
- Belongs to an artifact collection with a version sequence (v1, v2, v3, …)
- Can be attached to a deployment
- Provides a stable reference for production workloads

You can create a registered artifact by promoting a draft, or by registering directly without going through the draft stage.

## Artifact types

Artifacts are polymorphic—the `type` field determines the expected behavior and constraints. The API treats all artifact types generically, but validation and backend behavior vary by type.

> [!NOTE] DataRobot 11.4
> DataRobot 11.4 supports the container type only.

Artifact types include:

| Type | Description |
| --- | --- |
| generic | General-purpose containerized service |
| agent | AI agents with specific interface requirements |
| model | Machine learning models for inference |
| graph | Multi-component graph for an application |
| nim | NVIDIA NIM containers for optimized inference |

The artifact type affects expected container interfaces, telemetry behavior, and deployment compatibility.

## Workloads

A workload represents live compute. When you create a workload from an artifact, the system provisions the necessary resources and manages the runtime lifecycle.

### Workload states

Workloads progress through a defined lifecycle:

| State | Description |
| --- | --- |
| Submitted | The workload request has been accepted |
| Initializing | Resources are being provisioned and containers are starting |
| Running | The workload is active and serving requests |
| Stopped | The workload has been intentionally stopped |
| Errored | The workload encountered a failure |

### Creating workloads

You can create workloads in two ways:

- From an existing artifact: Reference a previously created artifact by ID. Use this when you want to reuse the same artifact configuration across multiple workloads.
- With an inline artifact definition: Include the artifact specification directly in the workload creation request. Use this for rapid iteration without separate artifact management.

### Draft vs. registered workloads

A workload's eligibility for production depends on its underlying artifact:

- Draft workloads use draft artifacts. They are suited for development and testing but cannot be attached to a deployment.
- Registered workloads use registered artifacts. They are eligible for governance controls and can be attached to a deployment for production use.

Only a workload whose artifact is registered can be linked to a deployment. After you promote an artifact to registered, any workload using that artifact is no longer draft-capable; the artifact (and thus the workload's configuration) is immutable.

## Deployments

Deployments provide the production-facing layer of the Workload API. A deployment wraps a single workload and provides:

- A stable URL that persists across workload updates
- Health monitoring and status endpoints
- Access control and authentication
- Audit logging and governance integration

Each deployment can have only one active workload at a time and provides a stable external identity for that workload.

> [!NOTE] Distinct from model deployments
> Workload API deployments are a new concept, separate from DataRobot model deployments. They do not share the same data model or APIs.

## Resource bundles

Resource bundles define the compute resources allocated to a workload. Instead of specifying raw CPU, memory, and GPU requirements directly, you select a bundle that matches your workload's needs.

Bundles abstract the underlying infrastructure and may include:

- CPU allocation
- Memory allocation
- GPU type and count
- GPU memory

This abstraction enables workload portability across different infrastructure configurations and simplifies resource management.

## Current capabilities and limitations

### Supported

- Bring your own container (BYOC): Containers must be pre-built and published to a registry accessible by the DataRobot cluster.
- Container definitions: Ports, entrypoints/commands, environment variables, and Kubernetes-style probes (liveness, readiness, startup).
- Artifact lifecycle: Draft → registered, with versioning via artifact collections.
- Workload lifecycle: Create, start, and stop workloads.
- Production deployments: Stable invoke URLs and a governance layer (access control, audit logging).

### Current limitations

- DataRobot Secrets integration is not yet available; use environment variables or your own secret management.
- Replacing the workload underlying a deployment (workload swap) is not yet supported.
- You cannot build or customize container images via the API; use an external registry and image build pipeline.
- Telemetry (metrics, logs, traces) for draft workloads is limited compared to deployment-backed workloads.

## Design principles

The Workload API is built around several key design principles:

| Principle | Description |
| --- | --- |
| Separation of concerns | Artifacts define business logic independently from runtime configuration. The same artifact can be reused across environments and deployment scenarios. |
| Immutability for production | Registered artifacts are immutable, providing a reliable foundation for auditing, rollbacks, and reproducibility. |
| Progressive governance | Draft resources enable rapid experimentation without governance overhead. Governance controls apply only when resources are registered for production use. |
| Infrastructure abstraction | The API intentionally hides Kubernetes primitives and infrastructure details. You work with business-level concepts rather than low-level orchestration. |

---
