API Overview

Introduction

The ClawHosters API lets you manage your instances, check billing, and control add-ons programmatically. It is a REST API that accepts and returns JSON.

Base URL:

https://clawhosters.com/api/v1

All endpoints are versioned under /api/v1.

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header of every request.

Authorization: Bearer oc_live_your_api_key_here

Getting an API Key

1. Go to Dashboard > Settings > API Keys
2. Click Create API Key
3. Give your key a name (e.g., "My Script")
4. Copy the key immediately — it is only shown once

API keys start with the prefix oc_live_ followed by a unique token string. Store your key securely and do not share it.

Key Management

• Each account can have multiple API keys
• Keys can be revoked at any time from the dashboard
• Revocation is immediate and cannot be undone
• Keys support optional expiration dates

Rate Limiting

The API enforces a rate limit of 100 requests per minute per API key.

Every response includes rate limit headers:

When the limit is exceeded, the API returns a 429 Too Many Requests status.

Request Format

Send requests with Content-Type: application/json. Include your API key in the Authorization header.

Example request:

curl -X GET https://clawhosters.com/api/v1/instances \
  -H "Authorization: Bearer oc_live_your_api_key_here" \
  -H "Content-Type: application/json"

Example POST request:

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

Response Format

All responses are JSON. Successful responses wrap data in a data key.

Single resource:

{
  "data": {
    "id": 42,
    "name": "my-bot",
    "status": "running"
  }
}

List with pagination:

{
  "data": [
    { "id": 42, "name": "my-bot" },
    { "id": 43, "name": "test-bot" }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_count": 52,
    "per_page": 25
  }
}

Error Responses

Errors return a JSON object with an error key containing a machine-readable code and a human-readable message.

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

Validation errors include a details field:

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Validation failed",
    "details": {
      "name": "is required"
    }
  }
}

HTTP Status Codes

Available Endpoints

Health

Account

Instances

Billing

Add-ons

Backups

Versioning

The API is versioned through the URL path. The current version is v1. When breaking changes are introduced, a new version will be released while the previous version remains available.

Related Documentation

• Billing Overview — How billing, Claws, and payments work
• Instance Overview — Instance lifecycle and statuses
• Troubleshooting Common Issues — Solutions for common problems