---
title: "Suspend a tenant"
description: "Trillet OEM API: Stops the tenant's traffic and keeps everything else."
openapi: /public/openapi/trillet-oem.yaml POST /partner/v1/tenants/{tenantId}/suspend
lastUpdated: "2026-10-28"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.trillet.ai/llms.txt). Append `.md` to any page URL for its markdown version.

`POST https://api.trillet.ai/partner/v1/tenants/{tenantId}/suspend`

Stops the tenant's traffic and keeps everything else. Outbound calls, web calls and SMS are
refused, new workflow runs are skipped, and inbound calls are answered and ended at once.
Needs `tenants:write`.

## Authentication

- `partnerKey` — http bearer (tpk_live_...)

## Request body

- Content type: `application/json`
  - request body (object)
    - `reason` (string) — Returned as `suspendedReason`.

## Response 200

The tenant, with status `suspended`.
  - response (object)
    - `object` (string, required)
    - `id` (string, required) — Use it in paths and as `x-workspace-id` on standard endpoints.
    - `externalId` (string, required) — Your ID for this customer.
    - `name` (string, required)
    - `status` (string, required, one of: active, suspended, deleted, provisioning_failed)
    - `region` (string, required, one of: us, au)
    - `metadata` (object, required)
    - `limits` (object, required)
      - `monthlySpendCap` (number | null) — Monthly spend cap in USD. `null` means no cap. `0` blocks all paid work.
    - `suspendedAt` (string | null, date-time)
    - `suspendedReason` (string | null)
    - `deletedAt` (string | null, date-time)
    - `createdAt` (string, date-time, required)

## Response 400

The request is malformed or a field is invalid. `error.param` names the field when there is one.
  - response (object)
    - `error` (object, required)
      - `type` (string, required, one of: invalid_request_error, authentication_error, permission_error, conflict_error, rate_limit_error, api_error, idempotency_error)
      - `code` (string, required) — A stable code. Handle errors by `code`, not by `message`.
      - `message` (string, required)
      - `param` (string) — The request field the error is about, when there is one.
      - `requestId` (string | null) — Include it when you contact support. Not present on idempotency errors.

## Response 401

The partner key is missing, malformed, unknown or revoked (`partner_key_required`, `invalid_api_key`, `partner_not_enabled`).
  - response (object)
    - `error` (object, required)
      - `type` (string, required, one of: invalid_request_error, authentication_error, permission_error, conflict_error, rate_limit_error, api_error, idempotency_error)
      - `code` (string, required) — A stable code. Handle errors by `code`, not by `message`.
      - `message` (string, required)
      - `param` (string) — The request field the error is about, when there is one.
      - `requestId` (string | null) — Include it when you contact support. Not present on idempotency errors.

## Response 403

`missing_scope`, or `key_restricted` on webhook endpoint routes.
  - response (object)
    - `error` (object, required)
      - `type` (string, required, one of: invalid_request_error, authentication_error, permission_error, conflict_error, rate_limit_error, api_error, idempotency_error)
      - `code` (string, required) — A stable code. Handle errors by `code`, not by `message`.
      - `message` (string, required)
      - `param` (string) — The request field the error is about, when there is one.
      - `requestId` (string | null) — Include it when you contact support. Not present on idempotency errors.

## Response 404

Not found, or not yours. For example `tenant_not_found`.
  - response (object)
    - `error` (object, required)
      - `type` (string, required, one of: invalid_request_error, authentication_error, permission_error, conflict_error, rate_limit_error, api_error, idempotency_error)
      - `code` (string, required) — A stable code. Handle errors by `code`, not by `message`.
      - `message` (string, required)
      - `param` (string) — The request field the error is about, when there is one.
      - `requestId` (string | null) — Include it when you contact support. Not present on idempotency errors.


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://docs.trillet.ai/api-specs.zip