# API reference

> API reference - REST API reference including endpoints, schemas, and HTTP status codes.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-05-06T18:17:09.609411+00:00` (UTC).

## Primary page

- [API reference](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html): Full documentation for this topic (HTML).

## Sections on this page

- [Authentication](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#authentication): In-page section heading.
- [Base URLs](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#base-urls): In-page section heading.
- [Workload endpoints](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#workload-endpoints): In-page section heading.
- [POST /console/workloads/ — Create workload](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#post-workloads): In-page section heading.
- [GET /console/workloads/ — List workloads](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#get-workloads): In-page section heading.
- [GET /console/workloads/{workloadId}/ — Get workload](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#get-workload): In-page section heading.
- [POST /console/workloads/{workloadId}/start — Start workload](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#post-workload-start): In-page section heading.
- [POST /console/workloads/{workloadId}/stop — Stop workload](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#post-workload-stop): In-page section heading.
- [DELETE /console/workloads/{workloadId}/ — Delete workload](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#delete-workload): In-page section heading.
- [Artifact endpoints](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#artifact-endpoints): In-page section heading.
- [Deployment endpoints](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#deployment-endpoints): In-page section heading.
- [POST /console/deployments/ — Create deployment](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#post-deployments): In-page section heading.
- [Other deployment endpoints](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#other-deployment-endpoints): In-page section heading.
- [Schema reference](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#schema-reference): In-page section heading.
- [WorkloadStatus](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#workload-status): In-page section heading.
- [ArtifactStatus](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#artifact-status): In-page section heading.
- [ResourceRequest](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#resource-request): In-page section heading.
- [ProbeConfig](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#probe-config): In-page section heading.
- [ScalingMetricType](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#scaling-metric-type): In-page section heading.
- [HTTP status codes](https://docs.datarobot.com/en/docs/api/dev-learning/workload-api/api-reference.html#http-status-codes): In-page section heading.

## Related documentation

- [Developer documentation](https://docs.datarobot.com/en/docs/api/index.html): Linked from this page.

## Documentation content

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