Workloads

Workloads are compute jobs on Targon. The API uses a register-then-deploy flow:

1. Register — POST /tha/v3/orgs/{org_slug}/workloads saves configuration. State is registered.
2. Deploy — POST /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/deploy provisions runtime resources.

Updating a running workload (outside registered, suspended, or deleted) triggers an automatic redeploy.

Workload types

SANDBOX

Short-lived isolated environment created from a sandbox template. Supports timeouts, forking, exec, files, interactive terminals, desktop access, and publishing reusable templates. See the Sandboxes API.

VM

Virtual machine deployed via the Targon VM master. Optional vm_config.hostname (defaults to the workload name). Maps to inventory type vm.

See the Virtual Machines guide for dashboard workflows and SSH access.

BM

Dedicated physical server claimed from Targon Mainframe. Requires region and at least one SSH key. Optional bm_config.hostname and reservation_uid. Maps to inventory type bm.

See the Bare Metal guide for region selection and SSH access.

Lifecycle states

Status	Description
registered	Created; awaiting deploy
provisioning	Deploy in progress
running	Healthy / ready
error	Failure
suspended	Suspended; runtime removed (not supported for VM)
stopped	Frozen sandbox; can be restored with thaw
deleted	Soft-deleted

Authentication

All workload endpoints are scoped to an organization. Replace {org_slug} with your organization slug.

Authenticate with a personal access token or org service token:

Authorization: Bearer <YOUR_API_TOKEN>

JSON request bodies reject unknown fields.

Pagination: list endpoints accept limit (default 1000) and cursor (UID of the last item from the previous page). Responses include next_cursor.

---

Create Workload

POST /tha/v3/orgs/{org_slug}/workloads

Request body

Field	Type	Description
type	string	Required. SANDBOX, VM, or BM
name	string	Required. Lowercase alphanumeric and hyphens, max 32 characters
image	string	Required. Sandbox template UID (SANDBOX), VM image name (VM), or BM image name (BM)
resource_name	string	Required for VM and BM. Omit for SANDBOX because the template fixes the resource
region	string	Required for BM. Active region UID (lowercase slug, max 32 characters). Not for other types
reservation_uid	string	Bind to an ACTIVE reservation. VM and BM only
ports	array	Port mappings. See Port object. Not for BM
ssh_keys	array	SSH key UIDs to attach. Required for BM
sandbox_config	object	Optional SANDBOX lifecycle settings. See Sandbox config
vm_config	object	Optional for VM. See VM config
bm_config	object	Optional for BM. See BM config
project_id	string	Optional project UID to assign the workload
experiments	object	Feature experiments (config-gated). Keys: reserved-gpu, persistent-workload. Not for BM

Port object

Field	Type	Description
port	integer	Required. 1024–65535
protocol	string	TCP, UDP, or SCTP (VM and SANDBOX: TCP / UDP only)
routing	string	PROXIED or DIRECT for supported workload types. Omit for SANDBOX

Env object

Field	Type	Description
name	string	Variable name
value	string	Variable value

Registry auth object

Field	Type	Description
server	string	Registry server URL
username	string	Registry username
password	string	Registry password or token

VM config

Field	Type	Description
hostname	string	RFC 1123 hostname (lowercase letters, digits, hyphens, dots; max 63 characters). Defaults to the workload name

Sandbox config

Field	Type	Description
ttl_sec	integer	Maximum lifetime in seconds. 0 or omitted disables automatic deletion
idle_timeout_sec	integer	Inactive seconds before freeze. 0 or omitted disables automatic freeze

BM config

Field	Type	Description
hostname	string	RFC 1123 hostname (lowercase letters, digits, hyphens, dots; max 63 characters). Defaults to the workload name

Example: Sandbox

curl -X POST https://api.targon.com/tha/v3/orgs/{org_slug}/workloads \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SANDBOX",
    "name": "agent-eval",
    "image": "sbt-python",
    "ssh_keys": ["shk-def456ghi789"],
    "sandbox_config": {
      "idle_timeout_sec": 300,
      "ttl_sec": 3600
    }
  }'

The workload is registered first. Deploy it with POST /orgs/{org_slug}/workloads/{workload_uid}/deploy. See the Sandboxes API for lifecycle, access, terminal, and desktop operations.

Example: VM

curl -X POST https://api.targon.com/tha/v3/orgs/{org_slug}/workloads \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-confidential-vm",
    "type": "VM",
    "image": "<vm-image-name>",
    "resource_name": "h200-small",
    "ssh_keys": ["shk-def456ghi789"],
    "vm_config": {
      "hostname": "my-confidential-vm"
    }
  }'

List available VM images with GET /tha/v3/orgs/{org_slug}/workloads/vm-images. See the Virtual Machines guide.

Example: Bare Metal

curl -X POST https://api.targon.com/tha/v3/orgs/{org_slug}/workloads \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-bare-metal",
    "type": "BM",
    "image": "<bm-image-name>",
    "resource_name": "<hardware-class>",
    "region": "us-ord-1",
    "ssh_keys": ["shk-def456ghi789"],
    "bm_config": {
      "hostname": "gpu-node-01"
    }
  }'

List available BM images with GET /tha/v3/orgs/{org_slug}/workloads/bm-images. List regions with GET /tha/v3/region. See the Bare Metal guide.

Response

Returns WorkloadOperationResponse:

Field	Type	Description
uid	string	Workload UID
type	string	Workload type
name	string	Workload name
image	string	Container image
reservation_uid	string	Bound reservation UID (VM / BM, when set)
cost_per_hour	number	Hourly cost (USD)
resource	object	Resource details
revision	string	Current revision
state	object	Current state
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

resource object: name, display_name, gpu_type, gpu_count, vcpu, memory, disk_size_mib, network_mode.

state object: status, message, urls, public_ip, ssh_port, ready_replicas, total_replicas.

---

List Workloads

GET /tha/v3/orgs/{org_slug}/workloads

Query	Type	Description
limit	integer	Max items
cursor	string	Pagination cursor
type	string	Filter by workload type
status	string	Filter by status
project_id	string	Filter by project UID
name	string	Filter by name

Returns { "items": [...], "next_cursor": "..." }. Each item is a WorkloadOperationResponse.

---

Get Workload

GET /tha/v3/orgs/{org_slug}/workloads/{workload_uid}

Returns the full Workload object, including ports and SSH keys. SANDBOX workloads include sandbox_config; VM workloads include vm_config (hostname); BM workloads include bm_config (region, hostname) and reservation_uid when bound.

---

Update Workload

PATCH /tha/v3/orgs/{org_slug}/workloads/{workload_uid}

All fields are optional. Supported fields depend on workload type. Sandboxes can update name, ports, ssh_keys, project_id, and sandbox_config; see Update a sandbox. Set project_id to "" to unassign a project.

---

Delete Workload

DELETE /tha/v3/orgs/{org_slug}/workloads/{workload_uid}

Returns 204 No Content. Tears down runtime and soft-deletes the workload.

---

Deploy Workload

POST /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/deploy

Starts provisioning. Returns WorkloadOperationResponse. Checks credits and inventory availability (region-scoped for BM).

BM deploys are single-attempt: a 409 WORKLOAD_BM_CLAIM_CONFLICT means no capacity matched and nothing was claimed.

---

Suspend Workload

POST /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/suspend

Suspends the workload and removes runtime resources. Not supported for VM or BM.

---

Reboot Workload

POST /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/reboot

Reboots a VM workload. Not supported for BM.

---

Get Workload State

GET /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/state

Field	Type	Description
uid	string	Workload UID
workload_type	string	Workload type
status	string	Current status
message	string	Status message
urls	array	{ "port", "url" } access URLs
public_ip	string	Public IP (when applicable)
ssh_port	integer	SSH port (when applicable)
ready_replicas	integer	Ready replica count
total_replicas	integer	Total replica count
updated_at	string	ISO 8601 timestamp

---

List Workload Events

GET /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/events

Query: limit, cursor.

Each event: workload_uid, workload_type, resource_name, event_type, pod_name, container_name, container_image, new_status, replica_count, old_replica_count, reason, message, display_message, exit_code, created_at.

---

Get Workload Logs

GET /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/logs

Query	Type	Description
since	string	RFC 3339 timestamp
tail	integer	Number of recent lines
follow	boolean	Stream logs (text/plain)
previous	boolean	Logs from previous container instance
type	string	VM only: serial or qemu

---

List VM Images

GET /tha/v3/orgs/{org_slug}/workloads/vm-images

Returns available VM images: { "name", "display_name", "description" }.

---

List BM Images

GET /tha/v3/orgs/{org_slug}/workloads/bm-images

Returns managed OS images for BM workloads: { "name", "display_name", "os_family" }. Pass name as image when creating a BM workload.

---

Verify Workload Digest

POST /tha/v3/orgs/{org_slug}/workloads/verify

Body: { "uid": string, "digest": string } (SHA256).

Response: { "verified": boolean }.

---

Attach / Detach SSH Key

PUT /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/ssh-keys/{ssh_key_uid} — empty body.

Response: { "workload_uid", "ssh_key_uid" }.

DELETE /tha/v3/orgs/{org_slug}/workloads/{workload_uid}/ssh-keys/{ssh_key_uid} — returns 204.

---

Errors

Errors return JSON: { "error": "message", "reason": "REASON_CODE" }.

Common status codes: 400 (validation), 401 (auth), 403 (forbidden), 404 (not found), 409 (conflict), 500 (server error).

VM-specific reason codes:

Reason	Status	Description
WORKLOAD_VM_HOSTNAME_INVALID	400	vm_config.hostname is not a valid RFC 1123 hostname

BM-specific reason codes:

Reason	Status	Description
WORKLOAD_BM_REGION_REQUIRED	400	region missing
WORKLOAD_BM_REGION_INVALID	400	region is not a lowercase slug ≤ 32 characters
WORKLOAD_BM_SSH_KEYS_REQUIRED	400	No ssh_keys supplied
WORKLOAD_BM_HOSTNAME_INVALID	400	bm_config.hostname is not a valid RFC 1123 hostname
WORKLOAD_BM_REGION_NOT_FOUND	409	region is not an active region
WORKLOAD_BM_RESERVATION_REGION_MISMATCH	409	Reservation is in a different region
WORKLOAD_BM_CLAIM_CONFLICT	409	No bare-metal capacity available for the request
WORKLOAD_BM_TARGET_NOT_FOUND	404	Image, reservation, or matching server not found
WORKLOAD_BM_SERVICE_UNAVAILABLE	503	Bare-metal control plane unavailable