API reference

Prepaid cloud VPS. Authenticated routes use NIP-98 unless using an API key.

Authentication

Sign a kind 27235 event with tags u (exact request URL) and method (HTTP verb). Event must be < 60s old. Send:

Authorization: Nostr <base64(JSON event)>

Autopay: add tag ["debit", "ndebit1…"] on pay and topup requests (not create).

Long-lived agents: POST /v1/auth/api-key → X-Api-Key: ndk_…. API keys cannot attach ndebit.

Customer agent skill

Autonomous agents should fetch and follow:

GET /agent-skill.md

Response envelope

{ "data": { … } }
{ "error": { "code": "…", "message": "…" } }

Public endpoints

Method	Path	Description
GET	/v1/health	Health check
GET	/v1/config	`markup_percent`, `payments_enabled`, `vapid_public_key`
GET	/v1/plans	Catalog by product line + `config_options`
GET	/v1/rates	BTC/USD spot
POST	/v1/orders/quote	Live quote → `retail_usd` + `amount_sats`

config_options keys

Keys are option_id strings from the catalog (not names like ram). Example shape after reading GET /v1/plans:

{
  "plan_id": "uuid-from-catalog",
  "pricing_id": 123,
  "hostname": "mybox.example.net",
  "ssh_key": "ssh-ed25519 AAAA…",
  "config_options": { "42": "32768", "43": "8", "45": "debian13-cloud" }
}

Orders

Method	Path	Description
POST	/v1/orders	Create → `pending_payment` (no invoice yet)
POST	/v1/orders/:id/pay	Get bolt11 or ndebit pull
POST	/v1/orders/:id/cancel	Cancel unpaid order
GET	/v1/orders	List orders
GET	/v1/orders/:id	Status, `progress`, `vm`, payment

VMs

Method	Path	Description
GET	/v1/vms	List + `ssh_hint`, `manage`
GET	/v1/vms/:id	VM detail
GET	/v1/vms/:id/credentials	Root password when no SSH key
POST	/v1/vms/:id/upgrade/preview	Price resource change
PATCH	/v1/vms/:id/upgrade	Apply resource change
PATCH	/v1/vms/:id/start	Power on
PATCH	/v1/vms/:id/stop	Power off
PATCH	/v1/vms/:id/restart	Restart
PATCH	/v1/vms/:id/reinstall	Reinstall OS
POST	/v1/vms/:id/ssh-key	Add SSH key live
POST	/v1/vms/:id/cancel	Cancel VM

Account

Method	Path	Description
GET	/v1/customers/me	Profile + `balance_usd`
PUT	/v1/customers/me/autopay	Save ndebit pointer
POST	/v1/customers/me/topup	Wallet topup (bolt11 or `paid: true`)
POST	/v1/auth/api-key	Mint API key
POST	/v1/push/subscribe	Web push (browser)

Order status flow

pending_payment → confirmed → provisioning → ready

Terminal: failed (read user_error) · canceled

Agent polling

GET /v1/plans — pick live plan + option IDs
POST /v1/orders with NIP-98 → pending_payment
POST /v1/orders/:id/pay — pay bolt11 or ndebit
Poll GET /v1/orders/:id every 2–3s until ready or failed
Connect via vm.ssh_hint, or GET /v1/vms/:id/credentials if password login