# Otwa Cloud API Reference

> Base URL: https://otwa.cloud/api/v1
> Authentication: Bearer token in Authorization header
> Format: JSON
> OpenAPI spec: https://otwa.cloud/openapi.json

## Authentication

All requests require an API key generated from your dashboard:
https://otwa.cloud/dashboard/api

```
Authorization: Bearer YOUR_API_KEY
```

### Permissions

- `account:read` — View account profile and balance
- `servers:read` — List servers, view credentials and live stats
- `servers:write` — Deploy, power, rename, and terminate servers
- `billing:read` — View balance and invoice history

---

## Account

### GET /account
Returns authenticated account details.
Requires: account:read

Response:
```json
{
  "id": "uuid",
  "email": "you@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "balance": "50.00",
  "tier": "standard",
  "createdAt": "2026-01-01T00:00:00.000Z"
}
```

---

## Products

### GET /products
List all available server plans. No authentication required.

Response:
```json
[
  {
    "id": "uuid",
    "name": "Starter",
    "vcpu": 2,
    "ramMb": 4096,
    "diskGb": 50,
    "bandwidthGb": 1000,
    "monthlyPrice": "10.00",
    "region": "OTWA IST"
  }
]
```

---

## Servers

### GET /servers
List all servers in your account with IPs.
Requires: servers:read

Response:
```json
[
  {
    "id": "uuid",
    "label": "prod-1",
    "status": "running",
    "ipAddress": "198.51.100.10",
    "os": "ubuntu-2404",
    "region": "OTWA IST",
    "vcpu": 2,
    "ramMb": 4096,
    "diskGb": 50,
    "additionalIps": [
      { "ip": "198.51.100.11", "gateway": "198.51.100.1", "netmask": "255.255.255.0", "cidr": "198.51.100.0/24" }
    ]
  }
]
```

### POST /servers
Deploy a new server. Deducts monthly cost from wallet.
Requires: servers:write

Request body:
```json
{
  "label": "prod-1",
  "productId": "uuid",
  "region": "OTWA IST",
  "os": "ubuntu-2404",
  "hostname": "srv1.example.com"
}
```

Response:
```json
{ "id": "uuid", "label": "prod-1", "status": "pending" }
```

### GET /servers/:id
Get full server detail including networking and specs blocks.
Requires: servers:read

Response:
```json
{
  "id": "uuid",
  "label": "prod-1",
  "status": "running",
  "networking": {
    "primaryIp": "198.51.100.10",
    "gateway": "198.51.100.1",
    "additionalIps": [
      { "ip": "198.51.100.11", "gateway": "198.51.100.1", "netmask": "255.255.255.0", "cidr": "198.51.100.0/24", "region": "OTWA IST" }
    ]
  },
  "specs": {
    "vcpu": 2,
    "ramMb": 4096,
    "ramGb": 4,
    "diskGb": 50,
    "bandwidthGb": 1000,
    "os": "ubuntu-2404",
    "region": "OTWA IST"
  }
}
```

### GET /servers/:id/credentials
Get SSH credentials for a server.
Requires: servers:read

Response:
```json
{
  "username": "root",
  "password": "G7xK2mP9qR3s",
  "ip": "198.51.100.10",
  "sshCommand": "ssh root@198.51.100.10"
}
```

### GET /servers/:id/stats
Live CPU, RAM, and disk usage. Returns null if server is not running.
Requires: servers:read

Response:
```json
{
  "cpu": 12.4,
  "memoryUsed": 1024,
  "memoryTotal": 4096,
  "diskUsed": 10,
  "diskTotal": 50
}
```

### PATCH /servers/:id/label
Rename a server.
Requires: servers:write

Request body:
```json
{ "label": "new-name" }
```

### POST /servers/:id/power/start
Power on a stopped server.
Requires: servers:write

### POST /servers/:id/power/stop
Power off a running server.
Requires: servers:write

### POST /servers/:id/power/reboot
Reboot a running server.
Requires: servers:write

### DELETE /servers/:id
Permanently terminate a server and release its IP. Irreversible.
Requires: servers:write

Response:
```json
{ "message": "Server termination queued" }
```

---

## Error Codes

| Code | Meaning |
|------|---------|
| 400  | Bad Request — missing or invalid parameters |
| 401  | Unauthorized — missing or invalid API key |
| 402  | Payment Required — insufficient wallet balance |
| 403  | Forbidden — API key lacks required permission |
| 404  | Not Found — resource does not exist |
| 429  | Too Many Requests — rate limit exceeded |

All errors return: `{ "message": "...", "statusCode": N }`

---

## Rate Limits

100 requests per minute per API key.
Exceeded requests receive 429 with Retry-After header.

---

## Quick Start

```bash
# 1. List your servers
curl https://otwa.cloud/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Deploy a server
curl -X POST https://otwa.cloud/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"prod-1","productId":"PLAN_ID","os":"ubuntu-2404"}'

# 3. Get SSH credentials
curl https://otwa.cloud/api/v1/servers/SERVER_ID/credentials \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Generate your API key: https://otwa.cloud/dashboard/api