Create a tenant

Provision a fully-isolated Swarmz workspace for one of your customers. Maps to WHMCS CreateAccount and is idempotent on your external reference.

POSThttps://api.swarmz.net/functions/v1/platform-create

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 id and the URL to drop the customer into their dashboard.

This is the only endpoint that does not accept a tenant_id, because the tenant doesn't exist yet — you address it by external_ref on every later call.

Parameters

Prop

Type

Request

curl -X POST https://api.swarmz.net/functions/v1/platform-create \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "whmcs:1234",
    "whu": { "email": "alice@example.com", "name": "Alice" },
    "entitlements": {
      "credits_per_day": 5,
      "max_projects": 3,
      "max_custom_domains": 1
    }
  }'

const res = await fetch('https://api.swarmz.net/functions/v1/platform-create', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    external_ref: 'whmcs:1234',
    whu: { email: 'alice@example.com', name: 'Alice' },
    entitlements: { credits_per_day: 5, max_projects: 3, max_custom_domains: 1 },
  }),
});

const data = await res.json();

import requests

res = requests.post(
    "https://api.swarmz.net/functions/v1/platform-create",
    headers={"Authorization": "Bearer sk_live_..."},
    json={
        "external_ref": "whmcs:1234",
        "whu": {"email": "alice@example.com", "name": "Alice"},
        "entitlements": {"credits_per_day": 5, "max_projects": 3, "max_custom_domains": 1},
    },
)
data = res.json()

Response

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

The dashboard_url host is derived from your account: your active custom domain if one is set, otherwise https://<your-slug>.swarmz.net.

Errors

Status	`error`	`reason`	When
400	`missing_fields`	`external_ref required`	`external_ref` absent or not a string
400	`missing_fields`	`whu.email required`	`whu.email` absent
400	`invalid_email`	—	Email failed validation
401	`unauthorized`	—	See Authentication
404	`account_not_found`	—	Defensive — your account row was not found
405	`method_not_allowed`	—	Anything other than `POST`
409	`account_inactive`	account status	Your platform account is not `active` (e.g. `draft`)
429	`rate_limited`	`per_key` / `per_ip`	Rate limit hit — see Rate limits
500	`provision_failed`	RPC message	Provisioning failed server-side; safe to retry

Idempotency

Retries are safe — but entitlements are not overwritten

platform-create is idempotent on (account, external_ref). A retried call returns the same tenant_id and dashboard_url, and never double-charges or double-provisions. A repeat call with different entitlements returns the existing tenant unchanged — patch it with platform-plan.

Notes

entitlements.credits_per_day: null (or omitting it) means unlimited. 0 forces the customer onto purchased top-ups only.
Once you call create with external_ref: "whmcs:1234", that value is locked to this tenant forever — never reuse it for a different service, even after termination.
We strongly recommend calling every later endpoint by external_ref rather than caching tenant_id — it survives panel restarts and DB migrations. See The external_ref convention.