Servers

VPS products use the same custom-checkout lifecycle as domains, but with server-specific configuration like image, region, backups, and post-purchase actions.

Agent_Flow

Example MCP-style transcript. Each request consumes the identifiers returned by the previous response.

text

1. catalog_search { category: "compute", q: "vps" }
2. catalog_checkout_requirements { catalogItemId }
3. quote_create {
     catalogItemId,
     quantity: 1,
     configuration: {
       hostname: "deploy-node-01",
       region: "eu-west",
       image: "ubuntu-24.04",
       billingTermMonths: 1,
       backupsEnabled: true
     }
   }
4. purchase_create { quoteId, idempotencyKey }
5. service_get { serviceId }
6. server_restart { serviceId }
7. server_reinstall { serviceId, image }

Step_1_Request_Search

json

{
  "tool": "catalog_search",
  "input": {
    "category": "compute",
    "q": "vps",
    "limit": 3
  }
}

Step_1_Response

json

{
  "items": [
    {
      "id": "cat_vps_micro",
      "sku": "vps-micro-monthly",
      "name": "VPS Micro",
      "category": "compute",
      "checkoutKind": "custom"
    },
    {
      "id": "cat_vps_small",
      "sku": "vps-small-monthly",
      "name": "VPS Small",
      "category": "compute",
      "checkoutKind": "custom"
    },
    {
      "id": "cat_vps_gpu_standard",
      "sku": "vps-gpu-standard",
      "name": "GPU Standard",
      "category": "compute",
      "checkoutKind": "custom"
    }
  ]
}

Step_2_Request_Checkout_Requirements

json

{
  "tool": "catalog_checkout_requirements",
  "input": {
    "catalogItemId": "cat_vps_micro"
  }
}

Step_2_Response

json

{
  "catalogItemId": "cat_vps_micro",
  "checkoutKind": "custom",
  "serviceType": "server",
  "requiredFields": [
    "hostname",
    "region",
    "image",
    "billingTermMonths"
  ],
  "supportedImages": [
    "ubuntu-24.04",
    "debian-12",
    "nvidia-ai-ubuntu"
  ]
}

Step_3_Request_Quote

json

{
  "tool": "quote_create",
  "input": {
    "catalogItemId": "cat_vps_micro",
    "quantity": 1,
    "configuration": {
      "hostname": "deploy-node-01",
      "region": "eu-west",
      "image": "ubuntu-24.04",
      "billingTermMonths": 1,
      "backupsEnabled": true
    }
  }
}

Step_3_Response

json

{
  "quote": {
    "id": "quote_srv_001",
    "catalogItemId": "cat_vps_micro",
    "totalPriceMinor": 2400,
    "currency": "usd",
    "configuration": {
      "hostname": "deploy-node-01",
      "region": "eu-west",
      "image": "ubuntu-24.04"
    },
    "managementCapabilities": [
      "server:restart",
      "server:reinstall"
    ]
  }
}

Step_4_Request_Purchase

json

{
  "tool": "purchase_create",
  "input": {
    "quoteId": "quote_srv_001",
    "idempotencyKey": "server-deploy-node-01-001"
  }
}

Step_4_Response

json

{
  "purchase": {
    "id": "purchase_srv_001",
    "status": "completed",
    "totalPriceMinor": 2400
  },
  "service": {
    "id": "svc_server_001",
    "serviceType": "server",
    "displayName": "deploy-node-01"
  }
}

Step_5_Request_Service_Get

json

{
  "tool": "service_get",
  "input": {
    "serviceId": "svc_server_001"
  }
}

Step_5_Response

json

{
  "service": {
    "id": "svc_server_001",
    "status": "active",
    "displayName": "deploy-node-01",
    "server": {
      "publicIpv4": "198.51.100.42",
      "sshUsername": "root",
      "sshPort": 22,
      "image": "ubuntu-24.04",
      "powerState": "running"
    }
  }
}

Step_6_Request_Restart

json

{
  "tool": "server_restart",
  "input": {
    "serviceId": "svc_server_001"
  }
}

Step_6_Response

json

{
  "serviceId": "svc_server_001",
  "status": "accepted",
  "server": {
    "powerState": "restarting"
  }
}

Step_7_Request_Reinstall

json

{
  "tool": "server_reinstall",
  "input": {
    "serviceId": "svc_server_001",
    "image": "nvidia-ai-ubuntu"
  }
}

Step_7_Response

json

{
  "serviceId": "svc_server_001",
  "status": "accepted",
  "server": {
    "image": "nvidia-ai-ubuntu",
    "provisioningStatus": "reinstalling"
  }
}

REST_Checkout

Quotes validate the requested region and system image, then return the final mock-provider price that purchase requests must use.

typescript

const quote = await fetch('https://ag3n7.store/v1/agent/quotes', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AGENT_STORE_AGENT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    catalogItemId: '<server-catalog-item-id>',
    quantity: 1,
    configuration: {
      hostname: 'deploy-node-01',
      region: 'eu-west',
      image: 'ubuntu-24.04',
      billingTermMonths: 1,
      backupsEnabled: true,
    },
  }),
}).then((res) => res.json());
 
const purchase = await fetch('https://ag3n7.store/v1/agent/purchases', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AGENT_STORE_AGENT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    quoteId: quote.quote.id,
    idempotencyKey: 'server-order-001',
  }),
}).then((res) => res.json());
 
const service = await fetch(`https://ag3n7.store/v1/agent/services/${purchase.service.id}`, {
  headers: { Authorization: `Bearer ${process.env.AGENT_STORE_AGENT_API_KEY}` },
}).then((res) => res.json());

Server_Management

After provisioning, service reads expose IP and SSH details. Management actions currently support restart and reinstall, and the dashboard surfaces the same state for human operators.

typescript

await fetch('https://ag3n7.store/v1/agent/services/<service-id>/server/restart', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AGENT_STORE_AGENT_API_KEY}`,
  },
});
 
await fetch('https://ag3n7.store/v1/agent/services/<service-id>/server/reinstall', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AGENT_STORE_AGENT_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    image: 'nvidia-ai-ubuntu',
  }),
});

Website_Checkout

Logged-in dashboard users now quote and purchase servers through the same backend catalog and quote endpoints used by agents, via a system-managed account checkout actor.