Volumes

Volumes are provisioned when attached to a RENTAL workload at deploy time. There is no standalone volume deploy endpoint.

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

Authentication

Volume endpoints require a personal access token or org service token:

Authorization: Bearer <YOUR_API_TOKEN>

---

Create Volume

Create a new persistent volume.

Endpoint

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

Request Body

Field	Type	Description
name	string	Required. Name for the volume.
size_in_mb	integer	Required. Size of the volume in megabytes.
resource_name	string	Required. The compute resource to provision the volume on.

Example Request

curl -X POST https://api.targon.com/tha/v3/orgs/{org_slug}/volumes \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-volume",
    "size_in_mb": 10240,
    "resource_name": "storage-rentals"
  }'

Response

Field	Type	Description
uid	string	Unique identifier for the volume.
state	object	Current state of the volume.

The state object:

Field	Type	Description
status	string	Current status of the volume.
message	string	Status message.
updated_at	string	ISO 8601 timestamp.

Example Response

{
  "uid": "vol-abc123def456",
  "state": {
    "status": "registered",
    "message": "",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Errors

Status Code	Description
400 - Bad Request	Invalid request body.
401 - Unauthorized	Invalid or missing API key.
500 - Internal Server Error	Server error.

---

List Volumes

List all volumes in the selected organization.

Endpoint

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

Query Parameters

Field	Type	Description
limit	integer	Maximum number of items to return.
cursor	string	Pagination cursor.
workload_uid	string	Filter volumes attached to a workload.

Example Request

curl -X GET "https://api.targon.com/tha/v3/orgs/{org_slug}/volumes?limit=10" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Response

Field	Type	Description
items	array	List of volume objects.
next_cursor	string	Cursor for the next page of results.

Each item in items:

Field	Type	Description
uid	string	Unique identifier for the volume.
name	string	Name of the volume.
size	integer	Size of the volume in megabytes.
resource_name	string	Compute resource the volume is on.
state	object	Current state of the volume.
cost_per_hour	number	Hourly cost of the volume.
mount_path	string	Mount path if attached to a workload.
workload_uid	string	UID of attached workload, if any.
pvc_name	string	Internal PVC name.
last_backup_at	string	ISO 8601 timestamp of last backup, if any.
deleted_by	string	Deletion reason (NEW_PVC, USER), if deleted.
created_at	string	ISO 8601 creation timestamp.
updated_at	string	ISO 8601 last update timestamp.

Example Response

{
  "items": [
    {
      "uid": "vol-abc123def456",
      "name": "my-volume",
      "size": 10240,
      "resource_name": "h200-small",
      "state": {
        "status": "running",
        "message": "",
        "updated_at": "2025-01-15T10:35:00Z"
      },
      "cost_per_hour": 0.05,
      "mount_path": "/data",
      "workload_uid": "wrk-xyz789abc123",
      "pvc_name": "pvc-vol-abc123",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:35:00Z"
    }
  ],
  "next_cursor": ""
}

Errors

Status Code	Description
400 - Bad Request	Invalid query parameters.
401 - Unauthorized	Invalid or missing API key.
500 - Internal Server Error	Server error.

---

Get Volume

Retrieve a volume by its UID.

Endpoint

GET /tha/v3/orgs/{org_slug}/volumes/{volume_uid}

Path Parameters

Field	Type	Description
volume_uid	string	Unique identifier of the volume.

Example Request

curl -X GET https://api.targon.com/tha/v3/orgs/{org_slug}/volumes/vol-abc123def456 \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Response

Returns the full volume object.

Example Response

{
  "uid": "vol-abc123def456",
  "name": "my-volume",
  "size": 10240,
  "resource_name": "h200-small",
  "state": {
    "status": "running",
    "message": "",
    "updated_at": "2025-01-15T10:35:00Z"
  },
  "cost_per_hour": 0.05,
  "mount_path": "/data",
  "workload_uid": "wrk-xyz789abc123",
  "pvc_name": "pvc-vol-abc123",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:35:00Z"
}

Errors

Status Code	Description
401 - Unauthorized	Invalid or missing API key.
403 - Forbidden	Not allowed.
404 - Not Found	Volume not found.
500 - Internal Server Error	Server error.

---

Get Volume State

Get the current state of a volume.

Endpoint

GET /tha/v3/orgs/{org_slug}/volumes/{volume_uid}/state

Path Parameters

Field	Type	Description
volume_uid	string	Unique identifier of the volume.

Example Request

curl -X GET https://api.targon.com/tha/v3/orgs/{org_slug}/volumes/vol-abc123def456/state \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Response

Field	Type	Description
uid	string	Unique identifier of the volume.
status	string	Current status of the volume.
message	string	Status message.
updated_at	string	ISO 8601 timestamp of last update.

Example Response

{
  "uid": "vol-abc123def456",
  "status": "running",
  "message": "",
  "updated_at": "2025-01-15T10:35:00Z"
}

Errors

Status Code	Description
401 - Unauthorized	Invalid or missing API key.
403 - Forbidden	Not allowed.
404 - Not Found	Volume not found.
500 - Internal Server Error	Server error.

---

List Volume Events

List lifecycle events for a volume.

Endpoint

GET /tha/v3/orgs/{org_slug}/volumes/{volume_uid}/events

Path Parameters

Field	Type	Description
volume_uid	string	Unique identifier of the volume.

Query Parameters

Field	Type	Description
limit	integer	Maximum number of items to return.
cursor	string	Pagination cursor.

Example Request

curl -X GET "https://api.targon.com/tha/v3/orgs/{org_slug}/volumes/vol-abc123def456/events?limit=20" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Response

Field	Type	Description
items	array	List of volume event objects.
next_cursor	string	Cursor for the next page of results.

Each item in items:

Field	Type	Description
volume_uid	string	Volume UID
cost_per_second	integer	Billing rate
resource_name	string	Resource name
event_type	string	Event type
namespace	string	Kubernetes namespace
pvc_name	string	PVC name
storage_class	string	Storage class
requested_size	string	Requested size
old_status	string	Previous status
new_status	string	New status
reason	string	Event reason
k8s_resource_version	string	K8s resource version
billing_status	string	Billing status
billing_processed_at	string	ISO 8601 billing timestamp
created_at	string	ISO 8601 event timestamp

Example Response

{
  "items": [
    {
      "volume_uid": "vol-abc123def456",
      "event_type": "STATUS_CHANGE",
      "old_status": "provisioning",
      "new_status": "running",
      "reason": "Volume bound",
      "resource_name": "h200-small",
      "pvc_name": "pvc-vol-abc123",
      "requested_size": "10Gi",
      "created_at": "2025-01-15T10:35:00Z"
    }
  ],
  "next_cursor": ""
}

Errors

Status Code	Description
400 - Bad Request	Invalid query parameters.
401 - Unauthorized	Invalid or missing API key.
403 - Forbidden	Not allowed.
404 - Not Found	Volume not found.
500 - Internal Server Error	Server error.

---

Update Volume

Update a volume's name.

Endpoint

PATCH /tha/v3/orgs/{org_slug}/volumes/{volume_uid}

Path Parameters

Field	Type	Description
volume_uid	string	Unique identifier of the volume.

Request Body

Field	Type	Description
name	string	Required. New name for the volume.

Example Request

curl -X PATCH https://api.targon.com/tha/v3/orgs/{org_slug}/volumes/vol-abc123def456 \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "renamed-volume"
  }'

Response

Returns the updated volume object.

Example Response

{
  "uid": "vol-abc123def456",
  "name": "renamed-volume",
  "size": 10240,
  "resource_name": "h200-small",
  "state": {
    "status": "running",
    "message": "",
    "updated_at": "2025-01-15T10:35:00Z"
  },
  "cost_per_hour": 0.05,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-16T08:00:00Z"
}

Errors

Status Code	Description
400 - Bad Request	Invalid request body.
401 - Unauthorized	Invalid or missing API key.
403 - Forbidden	Not allowed.
404 - Not Found	Volume not found.
500 - Internal Server Error	Server error.

---

Delete Volume

Delete a volume record.

Endpoint

DELETE /tha/v3/orgs/{org_slug}/volumes/{volume_uid}

Path Parameters

Field	Type	Description
volume_uid	string	Unique identifier of the volume.

Example Request

curl -X DELETE https://api.targon.com/tha/v3/orgs/{org_slug}/volumes/vol-abc123def456 \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Response

Returns 204 No Content on success.

Errors

Status Code	Description
401 - Unauthorized	Invalid or missing API key.
403 - Forbidden	Not allowed.
404 - Not Found	Volume not found.
500 - Internal Server Error	Server error.