Create a tenant

Provisions a new tenant — an isolated Swarmz workspace owned by your platform account — for one of your customers (a web-host user, or WHU). Returns the tenant's tenant_id and a dashboard_url to drop the customer into their dashboard.

This is the only endpoint that does not take a tenant_id, because the tenant does not exist yet. The id it returns is the tenant_id you use on every later call (plan, topup, sso, suspend, …). Set a stable external_ref here so create is safely retryable and so you have a fallback lookup handle if you ever lose the id.

Parameters

Request

curl -X POST https://api.swarmz.net/functions/v1/platform-create \
  -H "Authorization: Bearer sk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "whmcs:1234",
    "whu": { "email": "alice@example.com", "name": "Alice Martin" },
    "plan_code": "pro-monthly",
    "initial_prompt": "A booking site for my yoga studio with a class schedule and Stripe payments"
  }'

const res = await fetch('https://api.swarmz.net/functions/v1/platform-create', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    external_ref: 'whmcs:1234',
    whu: { email: 'alice@example.com', name: 'Alice Martin' },
    plan_code: 'pro-monthly',
    initial_prompt:
      'A booking site for my yoga studio with a class schedule and Stripe payments',
  }),
});

const data = await res.json();
// Persist data.tenant_id against your service record.

import requests

res = requests.post(
    "https://api.swarmz.net/functions/v1/platform-create",
    headers={"Authorization": "Bearer sk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"},
    json={
        "external_ref": "whmcs:1234",
        "whu": {"email": "alice@example.com", "name": "Alice Martin"},
        "plan_code": "pro-monthly",
        "initial_prompt": "A booking site for my yoga studio with a class schedule and Stripe payments",
    },
)
data = res.json()
# Persist data["tenant_id"] against your service record.

Response

{
  "ok": true,
  "tenant_id": "aa7d7fae-0386-4d8a-b977-72f856eac242",
  "dashboard_url": "https://swarmz.net/dashboard?workspace=aa7d7fae-0386-4d8a-b977-72f856eac242",
  "plan": { "success": true, "entitlements": { "...": "..." } },
  "initial_prompt_pending": true
}

Errors

Idempotency

See Idempotency for the account-wide model and The external_ref convention for how the key is locked.

Notes

• The id in tenant_id is the canonical address for the tenant. Persist it and use it on every later call; keep external_ref as your stable fallback handle.
• Once you create with external_ref: "whmcs:1234", that value is locked to this tenant forever — never reuse it for a different service, even after termination.
• On the plan_code path the workspace is created first (with any raw entitlements, normally none), then the plan's caps overwrite them. The plan is resolved against your account only, so you can never assign another reseller's plan.
• entitlements sanitization is forgiving: numeric knobs accept a finite value ≥ 0 or null (= unlimited); everything else for that knob is dropped silently rather than failing the call. See Entitlements.
• initial_prompt is best-effort by design: a storage miss never fails the provision, and a retried create can neither overwrite a still-pending prompt nor re-arm one the customer already consumed. Full lifecycle in Initial prompt.