Instance Management
Manage compute instances including creation, listing, deletion, and power control operations. All endpoints require authentication and enforce rate limits and resource quotas based on your subscription tier.
Create Instance
Create a new compute instance based on a template.
Endpoint: https://apis.threatwinds.com/api/compute/v1/instances
Method: POST
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Request Body
{
"template_id": "ubuntu-22-standard",
"zone": "us-central1-a"
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| template_id | string | Yes | Template identifier defining the instance image, machine type, and disk |
| zone | string | No | Zone for the instance. Defaults to {region}-a based on the template’s region |
Request
To create an instance, use a POST request:
curl -X 'POST' \
'https://apis.threatwinds.com/api/compute/v1/instances' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
"template_id": "ubuntu-22-standard",
"zone": "us-central1-a"
}'
Or using API key and secret:
curl -X 'POST' \
'https://apis.threatwinds.com/api/compute/v1/instances' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret' \
-H 'Content-Type: application/json' \
-d '{
"template_id": "ubuntu-22-standard",
"zone": "us-central1-a"
}'
Response
A successful response will return the created instance details.
Success Response (201 Created)
{
"id": "tw-550e84-a1b2c3d4",
"userId": "550e8400-e29b-41d4-a716-446655440000",
"name": "tw-550e84-a1b2c3d4",
"zone": "us-central1-a",
"machineType": "zones/us-central1-a/machineTypes/n1-standard-2",
"externalIp": "",
"internalIp": "",
"status": "PROVISIONING",
"templateId": "ubuntu-22-standard",
"createdAt": "2024-01-01T00:00:00Z"
}
Response Schema
| Field | Type | Description |
|---|---|---|
| id | string | Instance unique identifier |
| userId | string (UUID) | Owner user identifier |
| name | string | Instance name (auto-generated) |
| zone | string | Zone where instance is deployed |
| machineType | string | Machine type |
| externalIp | string | External IP address (empty until running) |
| internalIp | string | Internal IP address (empty until running) |
| status | string | Instance status |
| templateId | string | Template used to create the instance |
| createdAt | string (ISO 8601) | Creation timestamp |
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 201 | Created | Instance created successfully |
| 400 | Bad Request | Invalid JSON or missing required fields |
| 403 | Forbidden | Quota exceeded or missing authentication |
| 404 | Not Found | Template not found |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server-side error |
List Instances
List all instances for the authenticated user.
Endpoint: https://apis.threatwinds.com/api/compute/v1/instances
Method: GET
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Request
To list instances, use a GET request:
curl -X 'GET' \
'https://apis.threatwinds.com/api/compute/v1/instances' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'GET' \
'https://apis.threatwinds.com/api/compute/v1/instances' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (200 OK)
[
{
"id": "tw-550e84-a1b2c3d4",
"userId": "550e8400-e29b-41d4-a716-446655440000",
"name": "tw-550e84-a1b2c3d4",
"zone": "us-central1-a",
"machineType": "zones/us-central1-a/machineTypes/n1-standard-2",
"externalIp": "34.120.1.100",
"internalIp": "10.128.0.5",
"status": "RUNNING",
"templateId": "ubuntu-22-standard",
"createdAt": "2024-01-01T00:00:00Z"
}
]
Response Schema
Returns an array of Instance objects. See Create Instance for the Instance schema.
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 200 | OK | Request successful |
| 400 | Bad Request | Invalid user ID |
| 429 | Too Many Requests | Rate limit exceeded |
| 404 | Not Found | No instances found for user |
| 500 | Internal Server Error | Server-side error |
Get Instance
Get detailed information about a specific instance, including live status.
Endpoint: https://apis.threatwinds.com/api/compute/v1/instances/{id}
Method: GET
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| id | string | Yes | Instance identifier | tw-550e84-a1b2c3d4 |
Request
To get instance details, use a GET request:
curl -X 'GET' \
'https://apis.threatwinds.com/api/compute/v1/instances/tw-550e84-a1b2c3d4' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'GET' \
'https://apis.threatwinds.com/api/compute/v1/instances/tw-550e84-a1b2c3d4' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (200 OK)
{
"id": "tw-550e84-a1b2c3d4",
"userId": "550e8400-e29b-41d4-a716-446655440000",
"name": "tw-550e84-a1b2c3d4",
"zone": "us-central1-a",
"machineType": "zones/us-central1-a/machineTypes/n1-standard-2",
"externalIp": "34.120.1.100",
"internalIp": "10.128.0.5",
"status": "RUNNING",
"templateId": "ubuntu-22-standard",
"createdAt": "2024-01-01T00:00:00Z"
}
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 200 | OK | Request successful |
| 400 | Bad Request | Empty instance ID |
| 429 | Too Many Requests | Rate limit exceeded |
| 404 | Not Found | Instance not found or access denied |
| 500 | Internal Server Error | Server-side error |
Delete Instance
Terminate and permanently remove an instance.
Endpoint: https://apis.threatwinds.com/api/compute/v1/instances/{id}
Method: DELETE
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| id | string | Yes | Instance identifier | tw-550e84-a1b2c3d4 |
Request
To delete an instance, use a DELETE request:
curl -X 'DELETE' \
'https://apis.threatwinds.com/api/compute/v1/instances/tw-550e84-a1b2c3d4' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'DELETE' \
'https://apis.threatwinds.com/api/compute/v1/instances/tw-550e84-a1b2c3d4' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (204 No Content)
No response body is returned.
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 204 | No Content | Instance deleted successfully |
| 400 | Bad Request | Empty instance ID |
| 429 | Too Many Requests | Rate limit exceeded |
| 404 | Not Found | Instance not found or access denied |
| 500 | Internal Server Error | Server-side error |
Start Instance
Start a stopped compute instance.
Endpoint: https://apis.threatwinds.com/api/compute/v1/instances/{id}/start
Method: POST
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| id | string | Yes | Instance identifier | tw-550e84-a1b2c3d4 |
Request
curl -X 'POST' \
'https://apis.threatwinds.com/api/compute/v1/instances/tw-550e84-a1b2c3d4/start' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'POST' \
'https://apis.threatwinds.com/api/compute/v1/instances/tw-550e84-a1b2c3d4/start' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (202 Accepted)
No response body is returned. The start operation has been initiated.
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 202 | Accepted | Start operation initiated |
| 400 | Bad Request | Empty instance ID |
| 429 | Too Many Requests | Rate limit exceeded |
| 404 | Not Found | Instance not found or access denied |
| 500 | Internal Server Error | Server-side error |
Stop Instance
Stop a running compute instance (graceful shutdown).
Endpoint: https://apis.threatwinds.com/api/compute/v1/instances/{id}/stop
Method: POST
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| id | string | Yes | Instance identifier | tw-550e84-a1b2c3d4 |
Request
curl -X 'POST' \
'https://apis.threatwinds.com/api/compute/v1/instances/tw-550e84-a1b2c3d4/stop' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'POST' \
'https://apis.threatwinds.com/api/compute/v1/instances/tw-550e84-a1b2c3d4/stop' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (202 Accepted)
No response body is returned. The stop operation has been initiated.
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 202 | Accepted | Stop operation initiated |
| 400 | Bad Request | Empty instance ID |
| 429 | Too Many Requests | Rate limit exceeded |
| 404 | Not Found | Instance not found or access denied |
| 500 | Internal Server Error | Server-side error |
Restart Instance
Restart a compute instance. This performs a hard reset of the instance (equivalent to the reset operation).
Endpoint: https://apis.threatwinds.com/api/compute/v1/instances/{id}/restart
Method: POST
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| id | string | Yes | Instance identifier | tw-550e84-a1b2c3d4 |
Request
curl -X 'POST' \
'https://apis.threatwinds.com/api/compute/v1/instances/tw-550e84-a1b2c3d4/restart' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'POST' \
'https://apis.threatwinds.com/api/compute/v1/instances/tw-550e84-a1b2c3d4/restart' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (202 Accepted)
No response body is returned. The restart operation has been initiated.
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 202 | Accepted | Restart operation initiated |
| 400 | Bad Request | Empty instance ID |
| 429 | Too Many Requests | Rate limit exceeded |
| 404 | Not Found | Instance not found or access denied |
| 500 | Internal Server Error | Server-side error |
Reset Instance
Reset a compute instance (hard reset - equivalent to pressing the physical reset button). Unlike restart, this does not perform a graceful shutdown.
Endpoint: https://apis.threatwinds.com/api/compute/v1/instances/{id}/reset
Method: POST
Parameters
Headers
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Optional* | Bearer token for session authentication |
| api-key | string | Optional* | API key for key-based authentication |
| api-secret | string | Optional* | API secret for key-based authentication |
Note: You must use either Authorization header OR API key/secret combination.
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| id | string | Yes | Instance identifier | tw-550e84-a1b2c3d4 |
Request
curl -X 'POST' \
'https://apis.threatwinds.com/api/compute/v1/instances/tw-550e84-a1b2c3d4/reset' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'POST' \
'https://apis.threatwinds.com/api/compute/v1/instances/tw-550e84-a1b2c3d4/reset' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (202 Accepted)
No response body is returned. The reset operation has been initiated.
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 202 | Accepted | Reset operation initiated |
| 400 | Bad Request | Empty instance ID |
| 429 | Too Many Requests | Rate limit exceeded |
| 404 | Not Found | Instance not found or access denied |
| 500 | Internal Server Error | Server-side error |
Instance Status Values
| Status | Description |
|---|---|
| PROVISIONING | Instance is being created |
| RUNNING | Instance is active and running |
| STOPPING | Instance is shutting down |
| TERMINATED | Instance is stopped |
| STAGING | Instance is being started |
| SUSPENDED | Instance is suspended |
Power Operations Comparison
| Operation | Endpoint | Behavior | Use Case |
|---|---|---|---|
| Start | POST /instances/:id/start | Boot a stopped instance | Resume a terminated instance |
| Stop | POST /instances/:id/stop | Graceful OS shutdown | Safely shut down, preserving state |
| Restart | POST /instances/:id/restart | Hard reset | Reboot instance (same as reset) |
| Reset | POST /instances/:id/reset | Hard reset (no graceful shutdown) | Unresponsive instance recovery |