API: Instance Actions (Start/Stop/Restart)

Overview

Control your instance's power state using these endpoints. Each action changes the instance status and may take a few seconds to complete.

Check the can_start, can_stop, and can_restart fields from the Get Instance Details endpoint before calling these actions.

Start Instance

POST /api/v1/instances/:id/start

Powers on a stopped instance. The instance must be in stopped status.

Example:

curl -X POST https://clawhosters.com/api/v1/instances/42/start \
  -H "Authorization: Bearer oc_live_your_api_key_here"

Success Response (200 OK):

{
  "data": {
    "id": 42,
    "name": "my-ai-bot",
    "status": "running",
    "tier": "balanced",
    "can_start": false,
    "can_stop": true,
    "can_restart": true
  }
}

Stop Instance

POST /api/v1/instances/:id/stop

Powers off a running instance. The instance must be in running status. Data is preserved on the VPS.

Example:

curl -X POST https://clawhosters.com/api/v1/instances/42/stop \
  -H "Authorization: Bearer oc_live_your_api_key_here"

Success Response (200 OK):

{
  "data": {
    "id": 42,
    "name": "my-ai-bot",
    "status": "stopped",
    "tier": "balanced",
    "can_start": true,
    "can_stop": false,
    "can_restart": false
  }
}

Restart Instance

POST /api/v1/instances/:id/restart

Reboots a running instance. The instance must be in running status. There is a brief downtime during the restart.

Example:

curl -X POST https://clawhosters.com/api/v1/instances/42/restart \
  -H "Authorization: Bearer oc_live_your_api_key_here"

Success Response (200 OK):

{
  "data": {
    "id": 42,
    "name": "my-ai-bot",
    "status": "running",
    "tier": "balanced",
    "can_start": false,
    "can_stop": true,
    "can_restart": true
  }
}

Authentication

All action endpoints require a valid API key:

Authorization: Bearer oc_live_your_api_key_here

No request body is needed for any of these endpoints.

Error Responses

Unprocessable Entity (422)

Returned when the action is not available for the instance's current state. For example, trying to start a running instance.

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Instance cannot be started in its current state"
  }
}

Not Found (404)

The instance does not exist or belongs to a different customer.

{
  "error": {
    "code": "not_found",
    "message": "Instance not found"
  }
}

Unauthorized (401)

Returned when the API key is missing, invalid, or revoked.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Action Availability by Status

Notes

• Power actions are processed by the Hetzner Cloud API and may take a few seconds to complete. The response reflects the expected state after the action.
• Stopping an instance does not delete any data. The VPS remains allocated and can be started again at any time.
• Restarting performs a clean reboot of the Docker container and OpenClaw gateway.
• Daily billing continues for stopped instances since the VPS remains allocated. To stop billing completely, delete the instance or let it auto-pause when your Claws balance reaches zero.

Related Docs

• API Overview — Authentication, rate limits, and response format
• Get Instance Details — Check action availability before calling
• Delete Instance — Permanently remove an instance