API: Delete Instance

Endpoint

DELETE /api/v1/instances/:id

Permanently deletes an instance and its associated VPS. This action cannot be undone.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer oc_live_your_api_key_here

See API Overview for details on obtaining and managing API keys.

Request

Replace :id with the numeric instance ID. No request body is needed.

Example:

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

Response

Success (200 OK)

The server is queued for deletion. The instance status changes to deleting.

{
  "data": {
    "id": 42,
    "name": "my-ai-bot",
    "status": "deleting",
    "tier": "balanced",
    "billing_mode": "daily",
    "ip_address": null,
    "health_status": "unknown",
    "created_at": "2026-02-05T12:34:56Z",
    "provisioned_at": "2026-02-05T12:40:22Z",
    "can_start": false,
    "can_stop": false,
    "can_restart": false,
    "subdomain_url": "my-ai-bot.clawhosters.com",
    "daily_claw_cost": 225,
    "llm_configured": true,
    "telegram_configured": true
  }
}

What Happens During Deletion

1. The instance status is set to deleting
2. The Hetzner VPS is destroyed in the background
3. Daily billing stops for the instance
4. Any associated snapshots are cleaned up
5. The instance record is removed from your account

Error Responses

Not Found (404)

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

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

Unprocessable Entity (422)

Returned when the instance cannot be deleted in its current state (e.g., already deleting).

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

Unauthorized (401)

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

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

Notes

• Deletion is permanent. All data on the VPS is lost. If you have a backup add-on, existing backups are retained according to their retention policy.
• The instance continues to appear in list responses with status deleting until the background job completes.
• Daily billing stops the moment the delete request is accepted.
• If you want to temporarily stop an instance without losing data, use the stop action instead.

Related Docs

• API Overview — Authentication, rate limits, and response format
• Get Instance Details — View instance details before deleting
• List Instances — List all your instances