← Back to Docs

API Reference

Base URL: https://api.clawnaut.ai

🔐 Authentication

ClawNaut uses email OTP authentication. Request a code via /api/auth/request-otp, verify it to get a JWT bearer token, then include it in all requests:

Authorization: Bearer <your-jwt-token>

Tokens expire after 7 days.

💚Health

GET
/health

Simple liveness check

No auth required
GET
/api/health

Detailed health with DB status, uptime, and latency

No auth required

🔑Auth

POST
/api/auth/request-otp

Send a 6-digit OTP to an email address (max 5/hour)

No auth required
POST
/api/auth/verify-otp

Verify OTP and receive a JWT token (auto-creates account)

No auth required
GET
/api/auth/me

Get current authenticated user profile

🖥️Nodes

GET
/api/nodes

List all nodes for the authenticated user

POST
/api/nodes

Create a new node (provisions droplet, starts billing)

GET
/api/nodes/:id

Get node details with live status from DigitalOcean

DELETE
/api/nodes/:id

Delete a node (cancels billing, pro-rata refund, destroys droplet)

POST
/api/nodes/:id/start

Start a stopped node

POST
/api/nodes/:id/stop

Stop a running node

GET
/api/nodes/:id/config

Get OpenClaw configuration for a node

PUT
/api/nodes/:id/config

Update OpenClaw configuration (auto-pushed to live node)

POST
/api/nodes/:id/messages

Report cumulative message usage for billing

GET
/api/nodes/:id/usage

Get current message usage and estimated billing

💳Billing

POST
/api/billing/setup-intent

Create Stripe SetupIntent for collecting payment method

GET
/api/billing/payment-methods

List saved payment methods

DELETE
/api/billing/payment-methods/:id

Remove a payment method (can't remove last with active nodes)

GET
/api/billing/invoices

List invoices from Stripe

📊Metrics

GET
/api/metrics

Server metrics: request counts, error rates, latency percentiles, memory

No auth required

💰 Pricing

Node (monthly base)$19/month
Included messages1,000/month
Overage messages$0.05/msg

Pro-rata billing: charged daily for remainder of month on creation, refunded for unused days on deletion.

⚡ Rate Limits

Unauthenticated50 req / 15 min
Auth endpoints10 req / 15 min (per IP)
Free tier100 req / 15 min
Standard (1-2 nodes)300 req / 15 min
Premium (3+ nodes)1,000 req / 15 min

❌ Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": { ... }
  }
}

Common codes: BAD_REQUEST, VALIDATION_ERROR, UNAUTHORIZED, NOT_FOUND, RATE_LIMITED, NO_PAYMENT_METHOD, INVALID_STATE

🔄 Node Statuses

PROVISIONING — Droplet being created
ACTIVE — Running and reachable
STOPPED — Powered off
STARTING — Powering on
STOPPING — Powering off
ERROR — Operation failed
DELETING — Being torn down
DELETED — Permanently removed

Full OpenAPI spec available at GitHub — import into Postman, Insomnia, or any OpenAPI-compatible tool.