---
title: "put_tenant"
method: PUT
path: "/v1/tenants/{external_ref}"
tags: ["tenants"]
---

# put_tenant

`PUT /v1/tenants/{external_ref}`

## Request

- Base URL: `https://ndi-api.nace.ai`
- URL: `https://ndi-api.nace.ai/v1/tenants/{external_ref}`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/nace/apis/ndi-platform-api/docs/v1/tenants/:external_ref/put.ts> (a function with typed inputs; its response is checked against the schema)

Create the tenant, or update the one with this ``external_ref``.

Answers 201 when it was created and 200 when it already existed, so it is
safe to repeat. Limits above the partner's own are lowered to them.
Cost class: write.

## Path parameters

- `external_ref` string, required: The partner's own reference for the tenant, such as its account id.

## Request body

- PutTenantRequest: Create a tenant, or update the one with this ``external_ref``. Omitted fields stay as they are.
  - `data_retention` 'short' | 'zero_retention': Retention for document operations — a **client** setting, not a request field. A data-handling guarantee a caller can accidentally opt out of on one endpoint is not a guarantee, so this is configured per client at onboarding and appears in no request body.
  - `disabled` boolean, nullable: True disables the tenant (its requests answer tenant_disabled); false re-enables it.
  - `display_name` string, nullable: Human-readable name of the tenant.
  - `limits` TenantLimitsRequest: Per-tenant limits a partner asks for; values above the partner's own caps are lowered to them.
    - `max_concurrent_jobs` integer, nullable: Parse, split, classify, categorize, extract, ground and agent jobs this tenant may have running at once; more wait in the queue. NDI's own per-tenant cap applies when it is lower.
    - `rpm` integer, nullable: Requests per minute this tenant may make.
  - `workspace_storage_limit_bytes` integer, nullable: Allowance for current source-file bytes across this tenant’s managed workspaces. Omit to preserve the allowance; null removes it. Enforcement requires WORKSPACE_STORAGE_LIMITS_ENABLED.

## Response `200`

Successful Response

- Tenant: One of the partner's child tenants. Send ``X-NDI-Tenant: ext:<external_ref>`` to act for it.
  - `created_at` string, date-time, required: When the tenant was created.
  - `data_retention` 'short' | 'zero_retention', required: Retention for document operations — a **client** setting, not a request field. A data-handling guarantee a caller can accidentally opt out of on one endpoint is not a guarantee, so this is configured per client at onboarding and appears in no request body.
  - `disabled` boolean, required: Whether the tenant is disabled. Its data is kept.
  - `display_name` string, nullable, required: Human-readable name of the tenant.
  - `external_ref` string, required: The partner's own reference for the tenant, unique per partner.
  - `id` string, uuid, required: NDI's id for the tenant; X-NDI-Tenant accepts it too.
  - `limits` TenantLimits, required: The limits in force for a tenant.
    - `max_concurrent_jobs` integer, required: Parse, split, classify, categorize, extract, ground and agent jobs this tenant may have running at once; more wait in the queue. NDI's own per-tenant cap applies when it is lower.
    - `rpm` integer, required: Requests per minute this tenant may make.

## Other responses

- `201`: The tenant was created.
- `504`: Gateway Timeout
- `default`: Typed error envelope used by every 4xx and 5xx. ``error.code`` distinguishes the failure; HTTP status is a consequence of the code.

---

[API](https://skmtc.dev/nace/apis/ndi-platform-api.md) - [All operations](https://skmtc.dev/nace/apis/ndi-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/ndi-platform-api/revisions/d002a3589a67?raw)