Volumes provide persistent storage that can be attached to workloads. Data stored in volumes persists across workload restarts and redeployments.
Authentication
All volume endpoints require authentication using a Bearer token. Include your API key in the Authorization header:
Authorization: Bearer <YOUR_API_KEY>
Create Volume
Create a new persistent volume.
Endpoint
POST /tha/v2/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/v2/volumes \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "my-volume",
"size_in_mb": 10240,
"resource_name": "h200-small"
}'
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": "PROVISIONING",
"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 for the authenticated user.
Endpoint
GET /tha/v2/volumes
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/v2/volumes?limit=10" \
-H "Authorization: Bearer <YOUR_API_KEY>"
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. |
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": "READY",
"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/v2/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/v2/volumes/vol-abc123def456 \
-H "Authorization: Bearer <YOUR_API_KEY>"
Response
Returns the full volume object.
Example Response
{
"uid": "vol-abc123def456",
"name": "my-volume",
"size": 10240,
"resource_name": "h200-small",
"state": {
"status": "READY",
"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/v2/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/v2/volumes/vol-abc123def456/state \
-H "Authorization: Bearer <YOUR_API_KEY>"
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": "READY",
"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/v2/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/v2/volumes/vol-abc123def456/events?limit=20" \
-H "Authorization: Bearer <YOUR_API_KEY>"
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 | UID of the volume. |
event_type | string | Type of event. |
old_status | string | Previous status. |
new_status | string | New status. |
reason | string | Reason for the event. |
resource_name | string | Compute resource name. |
pvc_name | string | PVC name. |
requested_size | string | Requested volume size. |
created_at | string | ISO 8601 event timestamp. |
Example Response
{
"items": [
{
"volume_uid": "vol-abc123def456",
"event_type": "STATUS_CHANGE",
"old_status": "PROVISIONING",
"new_status": "READY",
"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/v2/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/v2/volumes/vol-abc123def456 \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-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": "READY",
"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/v2/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/v2/volumes/vol-abc123def456 \
-H "Authorization: Bearer <YOUR_API_KEY>"
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. |
Delete Volume Deployment
Delete deployed volume resources (the actual storage provisioned in the cluster) for a volume.
Endpoint
POST /tha/v2/volumes/{volume_uid}/delete
Path Parameters
| Field | Type | Description |
|---|
volume_uid | string | Unique identifier of the volume. |
Example Request
curl -X POST https://api.targon.com/tha/v2/volumes/vol-abc123def456/delete \
-H "Authorization: Bearer <YOUR_API_KEY>"
Response
Returns 202 Accepted with an operation response.
| Field | Type | Description |
|---|
uid | string | Unique identifier of the volume. |
state | object | Current state of the volume. |
Example Response
{
"uid": "vol-abc123def456",
"state": {
"status": "DELETING",
"message": "",
"updated_at": "2025-01-16T12:00: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. |