REST API

Launch and manage DeskBoot sessions from your own code — CI runners, browser farms, security training labs, ephemeral dev boxes, anything that spins VMs up and down on demand. JSON over HTTPS, Bearer-authenticated, no SDK required.

Authentication

Every request needs a personal access token (PAT) in the Authorization header. Create tokens at Settings → API tokens — they're shown exactly once.

Authorization: Bearer db_live_a1b2c3d4e5f6g7h8

Token format: db_live_prefix + 32 hex chars (128 bits of entropy). Tokens act with your user's permissions; revoke from the dashboard at any time.

Base URL

https://deskboot.store/api/v1

Endpoints

Examples

Who am I?

curl -H "Authorization: Bearer $DESKBOOT_TOKEN" \
  https://deskboot.store/api/v1/me

# →
{
  "id": "ckl3...",
  "email": "you@example.com",
  "trust_level": "TRUSTED",
  "preferred_currency": "USD",
  "balance_usd": 42.50,
  "created_at": "2026-05-12T08:23:11.000Z"
}

Launch a session

curl -X POST \
  -H "Authorization: Bearer $DESKBOOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"os":"ubuntu-24-04","size":"starter","region":"us-east-1"}' \
  https://deskboot.store/api/v1/sessions

# → 201 Created
{
  "session": {
    "id": "cmq8...",
    "status": "PROVISIONING",
    "os": "ubuntu-24-04",
    "size": "starter",
    "region": "us-east-1",
    "public_ip": null,
    "created_at": "2026-06-29T14:02:33.000Z"
  }
}

Poll until running

SESSION=$(curl -s -X POST -H "Authorization: Bearer $DESKBOOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"os":"ubuntu-24-04","size":"starter"}' \
  https://deskboot.store/api/v1/sessions | jq -r .session.id)

while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $DESKBOOT_TOKEN" \
    https://deskboot.store/api/v1/sessions/$SESSION | jq -r .session.status)
  echo "$STATUS"
  [ "$STATUS" = "RUNNING" ] && break
  sleep 5
done

Stop + terminate

# Stop (preserves data, ~$0.08/GB/mo storage continues)
curl -X POST -H "Authorization: Bearer $DESKBOOT_TOKEN" \
  https://deskboot.store/api/v1/sessions/$SESSION/stop

# Reboot
curl -X POST -H "Authorization: Bearer $DESKBOOT_TOKEN" \
  https://deskboot.store/api/v1/sessions/$SESSION/reboot

# Terminate (delete EBS too, irreversible)
curl -X DELETE -H "Authorization: Bearer $DESKBOOT_TOKEN" \
  https://deskboot.store/api/v1/sessions/$SESSION

Allocate + attach an Elastic IP

# Allocate ($5/mo)
EIP=$(curl -s -X POST -H "Authorization: Bearer $DESKBOOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"region":"us-east-1"}' \
  https://deskboot.store/api/v1/eips | jq -r .eip.id)

# Attach to a session — public_ip survives stop/start
curl -X POST -H "Authorization: Bearer $DESKBOOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"session_id\":\"$SESSION\"}" \
  https://deskboot.store/api/v1/eips/$EIP/attach

Redeem a voucher

curl -X POST -H "Authorization: Bearer $DESKBOOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"DBOOT-AB12-CD34"}' \
  https://deskboot.store/api/v1/vouchers/redeem

# →
{ "ok": true, "amount_usd": 5.00 }

CLI

There's no dedicated CLI binary yet — the API is already easy to script with curl + jq. Below is a one-file shell wrapper you can drop in ~/bin/db and call as db sessions list, db sessions launch ubuntu-24-04 starter, etc.

#!/usr/bin/env bash
# Save as ~/bin/db and chmod +x.
# Set DESKBOOT_TOKEN in your env first.
set -euo pipefail
BASE="https://deskboot.store/api/v1"
TOKEN="${DESKBOOT_TOKEN:?DESKBOOT_TOKEN not set}"
hdr=("-H" "Authorization: Bearer $TOKEN")

case "${1:-}" in
  me)        curl -s "${hdr[@]}" "$BASE/me" | jq . ;;
  sessions)
    shift
    case "${1:-}" in
      list)        curl -s "${hdr[@]}" "$BASE/sessions" | jq . ;;
      get)         curl -s "${hdr[@]}" "$BASE/sessions/$2" | jq . ;;
      launch)      curl -s -X POST "${hdr[@]}" -H "Content-Type: application/json" \
                     -d "{\"os\":\"$2\",\"size\":\"$3\",\"region\":\"${4:-us-east-1}\"}" \
                     "$BASE/sessions" | jq . ;;
      stop)        curl -s -X POST "${hdr[@]}" "$BASE/sessions/$2/stop" | jq . ;;
      start)       curl -s -X POST "${hdr[@]}" "$BASE/sessions/$2/start" | jq . ;;
      reboot)      curl -s -X POST "${hdr[@]}" "$BASE/sessions/$2/reboot" | jq . ;;
      terminate)   curl -s -X DELETE "${hdr[@]}" "$BASE/sessions/$2" | jq . ;;
      *)           echo "usage: db sessions {list|get|launch|stop|start|reboot|terminate}"; exit 1 ;;
    esac ;;
  eips)
    shift
    case "${1:-}" in
      list)    curl -s "${hdr[@]}" "$BASE/eips" | jq . ;;
      alloc)   curl -s -X POST "${hdr[@]}" -H "Content-Type: application/json" \
                 -d "{\"region\":\"${2:-us-east-1}\"}" "$BASE/eips" | jq . ;;
      attach)  curl -s -X POST "${hdr[@]}" -H "Content-Type: application/json" \
                 -d "{\"session_id\":\"$3\"}" "$BASE/eips/$2/attach" | jq . ;;
      detach)  curl -s -X POST "${hdr[@]}" "$BASE/eips/$2/detach" | jq . ;;
      release) curl -s -X DELETE "${hdr[@]}" "$BASE/eips/$2" | jq . ;;
      *)       echo "usage: db eips {list|alloc|attach|detach|release}"; exit 1 ;;
    esac ;;
  catalog)   curl -s "${hdr[@]}" "$BASE/catalog" | jq . ;;
  regions)   curl -s "${hdr[@]}" "$BASE/regions" | jq . ;;
  redeem)    curl -s -X POST "${hdr[@]}" -H "Content-Type: application/json" \
               -d "{\"code\":\"$2\"}" "$BASE/vouchers/redeem" | jq . ;;
  *) echo "usage: db {me|sessions|eips|catalog|regions|redeem} ..."; exit 1 ;;
esac

Errors

Errors are JSON with an error code and human-readable message:

{
  "error": "low_balance",
  "message": "Need at least $5.00 in balance to allocate an IP."
}

Limits

• No hard rate limits yet — we'll add them before they bite anyone
• Max 50 concurrent sessions per account (raise via contact)
• Voucher endpoint requires phone-verified + 1+ card on file
• EIP allocation requires TRUSTED status (after first paid top-up)

Coming next

• Firewall rules per session (open/close ports)
• Credentials API (download .rdp / SSH key)
• Webhooks for session.running / .terminated / balance.low
• OpenAPI spec for SDK generation