---
title: "Create a tenant"
description: "Trillet OEM API: Creates a tenant for one of your customers."
openapi: /public/openapi/trillet-oem.yaml POST /partner/v1/tenants
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`

Creates a tenant for one of your customers. Needs `tenants:write`. `Idempotency-Key` is required.

If the workspace is created but its setup does not complete, the tenant is returned with
status `provisioning_failed`.

## Authentication

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

## Header parameters

- `Idempotency-Key` (string, required) — 1 to 255 printable ASCII characters, no spaces. A retry with the same key and request returns the stored response for 24 hours instead of running again.

## Request body

- Content type: `application/json`
  - request body (object)
    - `externalId` (string, required) — Your ID for this customer. No leading or trailing spaces. Unique among your live tenants.
    - `name` (string, required)
    - `region` (string, one of: us, au) — Defaults to your partner account's region. Decides where call data is stored.
    - `metadata` (object) — Up to 8 KB of your own JSON data.
    - `limits` (object)
      - `monthlySpendCap` (number | null) — Monthly spend cap in USD. `null` means no cap. `0` blocks all paid work.

## Response 201

The new tenant.
  - 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 409

`tenant_exists`, `tenant_deleted_restorable`, `tenant_limit_reached`, or an idempotency conflict (`idempotency_key_in_use`).
  - 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 422

`idempotency_key_reused`: the same `Idempotency-Key` was sent with a different request.
  - 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