Admin — Instance Administration

Administrative endpoints for inspecting and controlling compute instances across all users and customers. These endpoints bypass ownership checks, rate limits, and quota enforcement, 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
pageSize int No Page size (default 20, max 100). 20
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, stopped, error, deleting). 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&pageSize=50' \
  -H 'Authorization: Bearer <token>'

Response

Success Response (200 OK) 

{
  "instances": [
    {
      "id": "inst-7g2xq4bm",
      "userId": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
      "customerId": "a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e",
      "name": "build-runner-03",
      "zone": "us-central1-a",
      "machineType": "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"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "totalCount": 812,
    "totalPages": 17,
    "hasNext": true,
    "hasPrev": false
  }
}

Response Schema

Field Type Description
instances array Array of instance objects.
instances[].id string Instance identifier.
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.
pagination object Standard pagination envelope.

Error Codes

Status Description Cause
200 OK Success.
400 Bad Request Invalid query parameters.
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the compute_admin role.

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. inst-7g2xq4bm

Request 

curl -X 'GET' \
  'https://apis.threatwinds.com/api/compute/v1/admin/instances/inst-7g2xq4bm' \
  -H 'Authorization: Bearer <token>'

Response 

{
  "id": "inst-7g2xq4bm",
  "userId": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
  "customerId": "a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e",
  "name": "build-runner-03",
  "zone": "us-central1-a",
  "machineType": "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.
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 underlying VM is shut down but the instance record and disk 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/inst-7g2xq4bm/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.
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.
409 Conflict Instance is not in a state that can be stopped.

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/inst-7g2xq4bm/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.
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.
409 Conflict Instance is not in a state that can be started.

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/inst-7g2xq4bm/restart' \
  -H 'Authorization: Bearer <token>'

Response

HTTP 202 Accepted with no body.

Error Codes

Status Description Cause
202 Accepted Restart queued.
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.
409 Conflict Instance is not in a state that can be restarted.

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/inst-7g2xq4bm/reset' \
  -H 'Authorization: Bearer <token>'

Response

HTTP 202 Accepted with no body.

Error Codes

Status Description Cause
202 Accepted Reset queued.
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.
409 Conflict Instance is not in a state that can be reset.