Admin — Instance Administration

Administrative endpoints for inspecting and controlling compute instances across all users and customers. These endpoints provide cross-tenant instance management capabilities for platform administrators, and require the caller to hold the compute_admin role.

Note: For self-service operations on instances you own, use the standard Instance Management endpoints instead.

Table of Content:

List all instances

Return a paginated list of every compute instance on the platform, with optional filters. Filters are combined with AND semantics.

Endpoint: https://apis.threatwinds.com/api/compute/v1/admin/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 the Authorization header OR the api-key/api-secret combination.

Query Parameters

Parameter Type Required Description Example
page int No Page number (default 1). 1
limit int No Items per page (default 10, max 100). Values above 100 or below 1 are reset to 10. 10
userID string No Filter by owning user. “5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e”
customerID string No Filter by owning customer. “a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e”
status string No Filter by instance status (PROVISIONING, RUNNING, STOPPING, STOPPED, STAGING). RUNNING
zone string No Filter by cloud zone. us-central1-a
templateID string No Filter by template identifier. ubuntu-22-standard

Request 

curl -X 'GET' \
  'https://apis.threatwinds.com/api/compute/v1/admin/instances?status=RUNNING&zone=us-central1-a&page=1&limit=10' \
  -H 'Authorization: Bearer <token>'

Response

Success Response (200 OK) 

{
  "instances": [
    {
      "id": "tw-5f35d2-8e9a1b2c",
      "userId": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
      "customerId": "a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e",
      "name": "tw-5f35d2-8e9a1b2c",
      "zone": "us-central1-a",
      "machineType": "zones/us-central1-a/machineTypes/n2-standard-4",
      "externalIp": "203.0.113.42",
      "internalIp": "10.128.0.12",
      "status": "RUNNING",
      "templateId": "ubuntu-22-standard",
      "createdAt": "2026-03-14T15:02:17Z"
    }
  ],
  "items": 1,
  "pages": 1
}

Response Schema

Field Type Description
instances array Array of instance objects.
instances[].id string Instance identifier (format: tw-XXXXXX-XXXXXXXX).
instances[].userId string UUID of the owning user.
instances[].customerId string UUID of the owning customer.
instances[].name string Instance name.
instances[].zone string Cloud zone the instance lives in.
instances[].machineType string Machine type / size.
instances[].externalIp string Public IP address (may be empty while provisioning).
instances[].internalIp string Private IP address.
instances[].status string Instance status.
instances[].templateId string Template the instance was created from.
instances[].createdAt string ISO 8601 creation timestamp.
items int Total number of items matching the query.
pages int Total number of pages available.

Error Codes

Status Description Cause
200 OK Success.
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the compute_admin role.
500 Internal Server Error Server failure.

Get any instance

Return the full record for a single instance, regardless of who owns it.

Endpoint: https://apis.threatwinds.com/api/compute/v1/admin/instances/{id}

Method: GET

Parameters

Headers

Same as List all instances.

Path Parameters

Parameter Type Required Description Example
id string Yes Instance identifier. tw-5f35d2-8e9a1b2c

Request 

curl -X 'GET' \
  'https://apis.threatwinds.com/api/compute/v1/admin/instances/tw-5f35d2-8e9a1b2c' \
  -H 'Authorization: Bearer <token>'

Response 

{
  "id": "tw-5f35d2-8e9a1b2c",
  "userId": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
  "customerId": "a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e",
  "name": "tw-5f35d2-8e9a1b2c",
  "zone": "us-central1-a",
  "machineType": "zones/us-central1-a/machineTypes/n2-standard-4",
  "externalIp": "203.0.113.42",
  "internalIp": "10.128.0.12",
  "status": "RUNNING",
  "templateId": "ubuntu-22-standard",
  "createdAt": "2026-03-14T15:02:17Z"
}

Error Codes

Status Description Cause
200 OK Success.
400 Bad Request Missing or malformed instance ID.
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the compute_admin role.
404 Not Found No instance with the given ID exists.

Stop any instance

Gracefully stop a running instance regardless of ownership. The instance is stopped but its configuration and data are preserved — call Start to boot it again.

Endpoint: https://apis.threatwinds.com/api/compute/v1/admin/instances/{id}/stop

Method: POST

Parameters

Headers same as List all instances. Path parameter is id as in Get any instance.

Request 

curl -X 'POST' \
  'https://apis.threatwinds.com/api/compute/v1/admin/instances/tw-5f35d2-8e9a1b2c/stop' \
  -H 'Authorization: Bearer <token>'

Response

HTTP 202 Accepted with no body. The stop operation is asynchronous — poll Get any instance to observe the status transition.

Error Codes

Status Description Cause
202 Accepted Stop queued.
400 Bad Request Missing or malformed instance ID.
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the compute_admin role.
404 Not Found No instance with the given ID exists.
500 Internal Server Error Instance is not in a valid state for this operation.

Start any instance

Boot a stopped instance regardless of ownership.

Endpoint: https://apis.threatwinds.com/api/compute/v1/admin/instances/{id}/start

Method: POST

Request 

curl -X 'POST' \
  'https://apis.threatwinds.com/api/compute/v1/admin/instances/tw-5f35d2-8e9a1b2c/start' \
  -H 'Authorization: Bearer <token>'

Response

HTTP 202 Accepted with no body. The start operation is asynchronous.

Error Codes

Status Description Cause
202 Accepted Start queued.
400 Bad Request Missing or malformed instance ID.
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the compute_admin role.
404 Not Found No instance with the given ID exists.
500 Internal Server Error Instance is not in a valid state for this operation.

Restart any instance

Gracefully restart an instance regardless of ownership. Equivalent to a stop + start cycle from the OS’s point of view.

Endpoint: https://apis.threatwinds.com/api/compute/v1/admin/instances/{id}/restart

Method: POST

Request 

curl -X 'POST' \
  'https://apis.threatwinds.com/api/compute/v1/admin/instances/tw-5f35d2-8e9a1b2c/restart' \
  -H 'Authorization: Bearer <token>'

Response

HTTP 202 Accepted with no body.

Error Codes

Status Description Cause
202 Accepted Restart queued.
400 Bad Request Missing or malformed instance ID.
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the compute_admin role.
404 Not Found No instance with the given ID exists.
500 Internal Server Error Instance is not in a valid state for this operation.

Reset any instance

Hard-reset an instance regardless of ownership. Equivalent to pulling the power cable and plugging it back in — the guest OS does not get a chance to shut down cleanly. Use for recovering from a hung guest; prefer Restart otherwise.

Endpoint: https://apis.threatwinds.com/api/compute/v1/admin/instances/{id}/reset

Method: POST

Request 

curl -X 'POST' \
  'https://apis.threatwinds.com/api/compute/v1/admin/instances/tw-5f35d2-8e9a1b2c/reset' \
  -H 'Authorization: Bearer <token>'

Response

HTTP 202 Accepted with no body.

Error Codes

Status Description Cause
202 Accepted Reset queued.
400 Bad Request Missing or malformed instance ID.
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the compute_admin role.
404 Not Found No instance with the given ID exists.
500 Internal Server Error Instance is not in a valid state for this operation.

Delete any instance

Force-delete any compute instance regardless of ownership. Synchronous: Permanently removes the instance and frees the customer’s instance quota slot. See Account Deletion Cascade.

Endpoint: https://apis.threatwinds.com/api/compute/v1/admin/instances/{id}

Method: DELETE

Parameters

Same headers and path parameters as Stop any instance.

Request 

curl -X 'DELETE' \
  'https://apis.threatwinds.com/api/compute/v1/admin/instances/tw-5f35d2-8e9a1b2c' \
  -H 'Authorization: Bearer <token>'

Response

204 No Content on success.

Error Codes

Status Description Cause
204 No Content Instance deleted.
400 Bad Request Missing or malformed instance ID.
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the compute_admin role.
404 Not Found No instance with the given ID exists.
500 Internal Server Error Server failure during deletion.