API reference¶
API version: v2.41 | Last updated: December 2025
This section provides the complete REST API reference for the DataRobot Workload API.
Authentication¶
All API requests require authentication using a Bearer token in the Authorization header:
Authorization: Bearer YOUR_API_TOKEN
Base URLs¶
| Endpoint group | Base path | Description |
|---|---|---|
| Workloads | /api/v2/console/workloads/ |
Workload lifecycle management. |
| Artifacts | /api/v2/registry/artifacts/ |
Container artifact registry. |
| Deployments | /api/v2/console/deployments/ |
Production deployment management. |
| Workload invoke | /api/v2/endpoints/workloads/{workloadId}/ |
Invoke a running workload (base URL; append your app path). |
| Deployment invoke | /api/v2/endpoints/deployments/{deploymentId}/ |
Invoke a deployment (base URL; append your app path). |
All endpoint paths in the sections below are relative to the API version root (e.g. https://app.datarobot.com/api/v2). Append the path to that base to form the full URL.
Workload endpoints¶
Endpoints in this section use the Workloads base path: /api/v2/console/workloads/.
POST /console/workloads/ — Create workload¶
Create a new workload from a user-provided artifact.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | No | Workload display name. |
artifact |
InputArtifact | Conditional | Inline artifact spec (required if no artifactId). |
artifactId |
string | Conditional | Existing artifact ID to deploy. |
runtime |
WorkloadRuntime | No | Replica count, autoscaling, resource bundle settings. |
Response: 201 Created → WorkloadFormatted
GET /console/workloads/ — List workloads¶
Retrieve a paginated list of workloads.
| Parameter | Type | Default | Description |
|---|---|---|---|
offset |
integer | 0 | Number of records to skip. |
limit |
integer | 100 | Records per page (max: 100). |
ids |
string[] | — | Filter by specific workload IDs. |
search |
string | — | Search by workload name. |
sort |
string | — | Sort order. |
GET /console/workloads/{workloadId}/ — Get workload¶
Retrieve details for a specific workload.
POST /console/workloads/{workloadId}/start — Start workload¶
Restart a stopped workload by scheduling it again.
Response: 202 Accepted
POST /console/workloads/{workloadId}/stop — Stop workload¶
Stop a running workload. Status transitions to stopping then stopped.
Response: 202 Accepted
DELETE /console/workloads/{workloadId}/ — Delete workload¶
Soft-delete a workload.
Response: 204 No Content
Artifact endpoints¶
Endpoints in this section use the Artifacts base path: /api/v2/registry/artifacts/.
| Method | Endpoint | Description | Response |
|---|---|---|---|
| POST | /registry/artifacts/ |
Create a new artifact in draft status. | 201 Created → ArtifactFormatted |
| GET | /registry/artifacts/ |
Retrieve a paginated list of artifacts. | — |
| GET | /registry/artifacts/{artifactId}/ |
Retrieve artifact details including full container specification. | — |
| PUT | /registry/artifacts/{artifactId}/ |
Fully replace an artifact's definition. | — |
| PATCH | /registry/artifacts/{artifactId}/ |
Partially update artifact metadata. | — |
| DELETE | /registry/artifacts/{artifactId}/ |
Soft-delete an artifact. | — |
Deployment endpoints¶
Endpoints in this section use the Deployments base path: /api/v2/console/deployments/.
POST /console/deployments/ — Create deployment¶
Create a new workload deployment.
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Deployment display name. |
workloadId |
string | Yes | ID of the workload to deploy. |
description |
string | No | Deployment description. |
importance |
string | No | Priority: critical, high, moderate, low. |
Other deployment endpoints¶
| Method | Endpoint | Description |
|---|---|---|
| GET | /console/deployments/ |
Retrieve a paginated list of workload deployments. |
| GET | /console/deployments/{deploymentId}/ |
Retrieve deployment details. |
| PATCH | /console/deployments/{deploymentId}/ |
Update deployment metadata. |
| DELETE | /console/deployments/{deploymentId}/ |
Delete a workload deployment. |
| GET | /console/deployments/{deploymentId}/stats/ |
Retrieve deployment statistics. |
Schema reference¶
WorkloadStatus¶
Workload lifecycle states:
| Status | Description |
|---|---|
unknown |
Status cannot be determined. |
submitted |
Workload created, not yet scheduled. |
initializing |
Containers being pulled and started. |
running |
Workload running and healthy. |
stopping |
Stop in progress. |
stopped |
Workload stopped. |
errored |
Error occurred (check statusDetails). |
ArtifactStatus¶
| Status | Description |
|---|---|
draft |
Artifact can be modified. |
registered |
Artifact locked for production use. |
ResourceRequest¶
Resource requirements for a container:
| Field | Type | Required | Description |
|---|---|---|---|
cpu |
number | Yes | CPU cores (can be fractional). |
memory |
integer | Yes | Memory in bytes. |
gpu |
integer | No | Number of GPUs. |
gpuType |
string | No | GPU type (e.g., NVIDIA-A10G). |
Memory examples: 1 GB = 1073741824, 4 GB = 4294967296, 16 GB = 17179869184
ProbeConfig¶
Health probe configuration for containers:
| Field | Type | Default | Description |
|---|---|---|---|
path |
string | — | HTTP path for health check (required). |
port |
integer | 8080 | Port number. |
scheme |
string | HTTP | Protocol: HTTP or HTTPS. |
initialDelaySeconds |
integer | 30 | Delay before first probe. |
periodSeconds |
integer | 30 | Time between probes. |
timeoutSeconds |
integer | 30 | Probe timeout. |
failureThreshold |
integer | 3 | Number of failures before marking unhealthy. |
ScalingMetricType¶
Available autoscaling metrics:
| Value | Description |
|---|---|
cpuAverageUtilization |
Scale based on average CPU utilization. |
httpRequestsPerHour |
Scale based on rolling hourly HTTP request rate. |
httpRequestsInFlight |
Scale based on concurrent in-flight requests. |
httpRequestsConcurrency |
Scale based on concurrency with scale-to-zero. |
HTTP status codes¶
| Code | Meaning | When used |
|---|---|---|
| 200 | OK | Successful GET, PUT, PATCH. |
| 201 | Created | Successful POST creating resource. |
| 202 | Accepted | Async operation started (start/stop). |
| 204 | No Content | Successful DELETE. |
| 400 | Bad Request | Malformed request. |
| 401 | Unauthorized | Missing or invalid token. |
| 403 | Forbidden | Insufficient permissions. |
| 404 | Not Found | Resource doesn't exist. |
| 422 | Validation Error | Invalid request body/params. |
| 500 | Server Error | Internal error. |