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 and network configuration.
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",
"config_id": "default-network"
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| template_id | string | Yes | Template identifier defining the instance image, CPU, and disk |
| config_id | string | Yes | Network configuration identifier defining zone, network, and tags |
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",
"config_id": "default-network"
}'
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",
"config_id": "default-network"
}'
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",
"configId": "default-network",
"createdAt": "2024-01-01T00:00:00Z",
"visibleBy": ["group1"]
}
Response Schema
| Field | Type | Description |
|---|---|---|
| id | string | Instance unique identifier |
| userId | string (UUID) | Owner user identifier |
| name | string | Instance name (auto-generated) |
| zone | string | GCP zone where instance is deployed |
| machineType | string | GCP 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 |
| configId | string | Network configuration used |
| createdAt | string (ISO 8601) | Creation timestamp |
| visibleBy | array of strings | Groups that can access this instance |
Business Logic
- Validates user ID and binds JSON request body
- Looks up the template to determine image, CPU, and disk configuration
- Looks up the network configuration to determine zone, network, and tags
- Creates the instance on Google Cloud Platform
- Saves the instance record to the datastore with
PROVISIONINGstatus - Enforces rate limits and quota checks before creation
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 or network configuration not found |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | GCP operation failed or datastore 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",
"configId": "default-network",
"createdAt": "2024-01-01T00:00:00Z",
"visibleBy": ["group1"]
}
]
Response Schema
Returns an array of Instance objects. See Create Instance for the Instance schema.
Business Logic
- Queries the datastore for all instances owned by the authenticated user
- Filters results based on group-based access control
- Returns 404 if no instances are found
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 | Datastore query error |
Get Instance
Get detailed information about a specific instance, including live status from GCP.
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",
"configId": "default-network",
"createdAt": "2024-01-01T00:00:00Z",
"visibleBy": ["group1"]
}
Business Logic
- Retrieves the instance record from the datastore
- Validates group-based access control
- Syncs the instance status, internal IP, and external IP with the live GCP state
- Returns the enriched instance object
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 | Datastore or GCP query 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.
Business Logic
- Retrieves the instance record and validates group-based access
- Deletes the instance from Google Cloud Platform
- Removes the instance record from the datastore
- GCP deletion errors are logged but do not block datastore cleanup
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 | Datastore deletion 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 | GCP start operation failed |
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 | GCP stop operation failed |
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 | GCP reset operation failed |
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 | GCP reset operation failed |
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 |