osModa API v2

Creates a new API key for programmatic access. The full key is returned only once.

Request Body

Response

{
  "key": "sk_live_a1b2c3d4e5f6...",  // Save this! Never shown again
  "id": "uuid",
  "name": "my-bot",
  "prefix": "sk_live_a1b2c3d4..."
}

Returns all active API keys. Full keys are never returned — only the prefix.

Response

{
  "keys": [{
    "id": "uuid", "name": "my-bot",
    "prefix": "sk_live_a1b2c3d4...",
    "created_at": "2026-03-07T...",
    "last_used": "2026-03-07T..."
  }]
}

Permanently revokes an API key. Takes effect immediately.

Returns all servers owned by the authenticated user with full status, health data, agent info, and channel connections.

Response

{
  "servers": [{
    "id": "uuid",
    "plan": "solo",
    "plan_name": "Solo Agent",
    "plan_price": 14.99,
    "status": "running",
    "server_ip": "1.2.3.4",
    "server_name": "osmoda-fb8f1012",
    "ssh_command": "ssh root@1.2.3.4",
    "last_heartbeat": "2026-03-07T...",
    "last_health": { "cpu": 12, "ram": 45, "disk": 23 },
    "agents": [{ "name": "osmoda", "status": "running", "model": "anthropic/claude-opus-4-6", "channels": [], "default": true }],
    "daemon_health": { ... },
    "ai_provider": "anthropic",
    "has_api_key": true,
    // ... 30+ more fields
  }]
}

Creates a Stripe checkout session for a new server. Returns a URL to redirect the user to for payment. Once paid, the server is provisioned automatically.

Request Body

Example

curl -X POST https://spawn.os.moda/api/dashboard/checkout \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"starter","region":"eu-central"}'

Response

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "order_ids": ["550e8400-e29b-41d4-a716-446655440000"]
}

Redirect the user to checkout_url. After payment, the server deploys automatically (~8 min).

Spawn a server using your account balance. Deducts the plan price immediately. Use this for programmatic deployments with your API key.

Request Body

Example

curl -X POST https://spawn.os.moda/api/dashboard/deploy \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"starter","region":"eu-central"}'

Response

{
  "success": true,
  "order_ids": ["uuid"],
  "quantity": 1,
  "plan": "Starter",
  "balance_remaining": 4501,
  "message": "Server deploying from balance. Allow 5-10 minutes."
}

Errors

Spawn a server with direct crypto payment (payment_tx + payment_chain). For automated deployments, use /api/dashboard/deploy with account balance instead.

Request Body

Destroys the Hetzner server and marks the order as deleted. Prorated refund is credited to your balance.

Wipes the server and reinstalls osModa from scratch. All data on the server is lost.

Request Body

Reads openclaw.json live from the server via SSH. Falls back to cached heartbeat data if SSH fails.

Response

{
  "agents": [
    {
      "id": "osmoda",
      "name": "osModa",
      "model": "anthropic/claude-opus-4-6",
      "default": true,
      "channels": []
    },
    {
      "id": "mobile",
      "name": "mobile",
      "model": "anthropic/claude-sonnet-4-6",
      "default": false,
      "channels": ["telegram", "whatsapp"]
    }
  ],
  "source": "live"
}

Creates a new agent on the server: adds to openclaw.json, creates workspace + session dirs, copies auth profile from the default agent, and restarts the gateway.

Request Body

Valid Models

Response

{
  "created": true,
  "agentId": "researcher",
  "model": "anthropic/claude-sonnet-4-6",
  "channels": ["telegram"]
}

Updates the model and/or channel bindings for an existing agent. Restarts the gateway.

Request Body

Removes the agent from openclaw.json and its channel bindings. Restarts the gateway. Cannot delete the default osmoda agent.

Configures the AI provider and API key for your server's agent. The key is encrypted before storage and delivered to the server via the next heartbeat.

Request Body

How it works

1. Your API key is encrypted with AES-256-GCM using a key derived from the server's heartbeat secret
2. The encrypted key is queued as a pending action
3. On the next heartbeat (~60s), the server pulls and decrypts the key locally
4. The key is written to the server's auth config and the AI gateway restarts
5. The plaintext key never touches our database

Removes the AI provider configuration and stops the agent gateway on the server.

Response

{
  "ssh_keys": ["ssh-ed25519 AAAA... user@host"]
}

Adds an SSH public key to the server's authorized_keys via the next heartbeat.

Request Body

Removes the SSH key at the given index (0-based). Get the index from the list endpoint.

Sends a message to the server's AI agent and waits for the complete response. This is the simplest way to interact with your agent programmatically.

Request Body

Query Parameters

Response

{
  "response": "System health check complete. CPU: 12%, RAM: 45%...",
  "truncated": false
}

Example

curl -X POST \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What services are running?"}' \
  "https://spawn.os.moda/api/dashboard/servers/SERVER_ID/chat?timeout=60"

For real-time streaming responses, connect via WebSocket. Requires cookie session auth (browser) or use the v1 chat endpoint with osk_ token.

v1 WebSocket (API token)

// Connect with osk_ token from v1 spawn
const ws = new WebSocket("wss://spawn.os.moda/api/v1/chat/ORDER_ID?token=osk_...");
ws.send(JSON.stringify({ type: "chat", text: "Hello agent" }));
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  // msg.event === "agent" && msg.payload.stream === "assistant"
  // msg.payload.data.delta = incremental text chunk
};

Returns provisioning and lifecycle log entries for the server.

SSHs into the server and returns recent journalctl output. Query params: lines (default 100), unit (systemd unit filter).

Lists files in a directory on the server via SSH. Query param: path (default /root).

Reads a file from the server via SSH. Query param: path (required, absolute path).

Scans the server for running web apps and services. Detects 8 types: systemd services, home/root projects, listening ports, Docker/Podman containers, nginx vhosts, Caddy domains, and osModa managed apps. Also returned in heartbeat data every 5 minutes.

SSHes into the server and triggers the heartbeat script immediately (instead of waiting for the 5-minute timer). Delivers any pending actions (SSH keys, API keys, channel connections) and refreshes all server data (health, agents, apps, daemons).

Response

{
  "triggered": true,
  "pending_count": 0,
  "message": "All actions synced successfully"
}

Returns your current account balance, monthly burn rate from running servers, and transaction history.

Example

curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  https://spawn.os.moda/api/dashboard/balance

Response

{
  "balance": 10000,              // cents ($100.00)
  "balance_formatted": "$100.00",
  "monthly_burn": 1499,           // cents/month from running servers
  "daily_burn": 50,               // cents/day
  "days_remaining": 200,           // days until balance runs out
  "active_servers": 1,
  "transactions": [{
    "id": "uuid",
    "type": "admin_credit",
    "amount": 10000,
    "description": "Admin credit — $100.00",
    "created_at": "2026-03-09T..."
  }]
}

Creates a Stripe checkout session to add funds to your account balance. Returns a URL to complete payment. After payment, the balance is credited automatically.

Request Body

Example

curl -X POST https://spawn.os.moda/api/dashboard/deposit \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50}'

Response

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "amount": "$50.00"
}

Redirect the user to checkout_url to complete the payment. Balance is credited instantly after payment.

Returns all support tickets created by you.

Request Body

Request Body

Returns available plans with x402 payment details. Accepts USDC on Base (EVM) or Solana (SVM).

Spawns a server with x402 USDC payment (Base or Solana). Returns an osk_ API token for managing the server.

Supported chains: Base (EVM, chain ID 8453) — Solana (SVM, mainnet-beta). The 402 response advertises both networks; your x402 client picks one.

Request Body

Response

{
  "order_id": "uuid",
  "api_token": "osk_...",  // Save this for v1 status/chat
  "status": "provisioning",
  "status_url": "https://spawn.os.moda/api/v1/status/uuid",
  "chat_url": "wss://spawn.os.moda/api/v1/chat/uuid"
}

Basic status is free. Full details (IP, health, agents) require Authorization: Bearer osk_...