All endpoints return application/json. Errors follow RFC 7807 (Problem+JSON). Every response carries an X-Request-Id header for correlation with the server-side audit log.
| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | /v1/health | public | Unauthenticated health check. |
| GET | /v1/me | any | Own account info + key metadata. |
| GET | /v1/products | read:products | List of all publicly listed products with prices. |
| GET | /v1/products/{id} | read:products | Product details including config options. |
| POST | /v1/orders | write:orders | Place an order. Idempotency-Key required. |
| GET | /v1/orders/{id} | read:orders | Status of an own order. |
| GET | /v1/services | read:services | List of own services (paginated). |
| GET | /v1/services/{id} | read:services | Details of an own service. |
| GET | /v1/services/{id}/credentials | read:credentials | Service credentials (separate scope, audit-logged). |
| POST | /v1/services/{id}/actions | write:services | Service action: start, stop, reboot, reinstall, suspend, unsuspend, terminate. |
| GET | /v1/billing/balance | read:billing | Credit balance. |
| GET | /v1/billing/invoices | read:billing | List of your invoices (paginated). |
| GET | /v1/billing/invoices/{id}/pdf | read:billing | Invoice PDF. |
| GET | /v1/webhooks | read:webhooks | Current webhook URL. |
| PUT | /v1/webhooks | write:webhooks | Set or unset webhook URL. |
Idempotency
POST /v1/orders and POST /v1/services/{id}/actions require an Idempotency-Key header (1-80 chars from [A-Za-z0-9_.-]). The server caches response + body hash for 24h; a second request with same key + same body returns the same response, a second request with same key but different body is rejected with 409 idempotency_conflict.
Rate limits
Default: 60 req/min (with 20-burst) and 5000/day per key, plus 600 req/min per IP independent of key. On excess, HTTP 429 with Retry-After header. Response headers X-RateLimit-Remaining and X-RateLimit-Reset expose current state.
