Suspend a tenant

Reversibly pause a tenant — flip it to suspended, take its public site offline, and tear down running infrastructure. The prior state is captured for unsuspend to replay.

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

Reversibly suspends a tenant. Maps to WHMCS SuspendAccount. The order is deliberate: client_status is flipped to suspended first, so any in-flight generation or publish sees the flag and refuses immediately. Then suspendWorkspace runs the teardown — projects are unpublished (the public site goes offline), custom domains are disconnected, preview pods are paused, and managed cloud is paused. The prior state is captured on the workspace so unsuspend can replay it.

Address the tenant by tenant_id — the id returned by create — or fall back to your external_ref. Supply exactly one identifier.

Parameters

Prop

Type

Request

curl -X POST https://api.swarmz.net/functions/v1/platform-suspend \
  -H "Authorization: Bearer sk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{ "tenant_id": "aa7d7fae-0386-4d8a-b977-72f856eac242" }'

const res = await fetch('https://api.swarmz.net/functions/v1/platform-suspend', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ tenant_id: 'aa7d7fae-0386-4d8a-b977-72f856eac242' }),
});

const data = await res.json();

import requests

res = requests.post(
    "https://api.swarmz.net/functions/v1/platform-suspend",
    headers={"Authorization": "Bearer sk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"},
    json={"tenant_id": "aa7d7fae-0386-4d8a-b977-72f856eac242"},
)
data = res.json()

Response

A fresh suspend returns the teardown report:

{
  "ok": true,
  "status": "suspended",
  "report": {
    "pausedPods": [],
    "unpublishedProjects": [],
    "disconnectedDomains": [],
    "pausedCloud": [],
    "errors": []
  }
}

If the tenant is already suspended, the call short-circuits before any teardown:

{ "ok": true, "status": "suspended", "already": true }

Field	Type	Description
`ok`	`boolean`	Always `true` on success.
`status`	`string`	Always `"suspended"`.
`already`	`boolean`	Present and `true` only when the tenant was already suspended (no teardown ran). Absent on a fresh suspend.
`report`	`object`	The teardown summary. Absent when `already: true`.
`report.pausedPods`	`string[]`	Identifiers of preview pods that were paused.
`report.unpublishedProjects`	`string[]`	Projects whose public site was taken offline.
`report.disconnectedDomains`	`string[]`	Custom domains that were disconnected.
`report.pausedCloud`	`string[]`	Managed-cloud resources that were paused.
`report.errors`	`string[]`	Per-step failures, if any (see callout below).

The status flip is authoritative even on partial teardown

Teardown collects errors and never throws. If a step fails, the tenant is still suspended (the status was flipped first) and the call still returns 200 with the failures listed in report.errors[]. Inspect that array and retry the failed steps out of band; do not treat a non-empty errors[] as a failed suspend.

Errors

Status	`error`	`reason`	When
400	`missing_fields`	`tenant_id or external_ref required`	Neither identifier supplied (bearer path)
400	`missing_fields`	`account_id required for internal suspend`	Internal-path call with no `account_id`
401	`unauthorized`	`missing_bearer` / `invalid_key` / `account_disabled`	See Authentication
404	`tenant_not_found`	—	No tenant matched the identifier under your account
405	`method_not_allowed`	—	Anything other than `POST`
410	`terminated`	—	The tenant has been terminated and cannot be suspended
429	`rate_limited`	`per_key` / `per_ip`	Rate limit hit — see Rate limits
500	`suspend_failed`	RPC message	The status-flip RPC (`platform_set_client_status`) failed; safe to retry
500	`internal_error`	—	Unhandled server error; safe to retry

Idempotency

Suspend is idempotent by state. An already-suspended tenant returns already: true and is not torn down twice. There is no idempotency key — the client_status is the source of truth. See Idempotency.

Notes

Suspend is reversible

Suspend captures the tenant's prior state so unsuspend can republish projects, rebind domains, and resume cloud. For a permanent, irreversible removal, use terminate instead.

Address the tenant by tenant_id from create; external_ref is the fallback.
A suspended tenant rejects sso (409 suspended), plan (409 suspended), and topup (409 suspended) — suspend is the lever for forcing a customer out immediately.
The account_id parameter and X-Internal-Mint-Secret path exist for the reseller dashboard's server-to-server calls only; host integrations use the bearer key and never send account_id.