Skip to main content
DELETE
JavaScript
This destroys the tenant, its subjects, every objective associated with it plus everything reachable from those objectives, and its widget sessions. Erasure is terminal: once it starts, nothing comes back. This is the endpoint for a customer offboarding or a “delete my data” request.

The work runs in the background

A large tenant’s history cannot be destroyed inside one request, so the response is the tenant in STATE_ERASING, not a count of what was removed. To follow it, poll Get a tenant: STATE_ERASING while it runs, NotFound once it finishes.

Wider than deleting widget sessions

Delete all of a tenant’s widget sessions removes only what widget sessions created. This endpoint is the full hammer: it takes the direct API objectives too, and the tenant record itself. Reach for the narrower one when the customer is only leaving your widget, and for this one when they are leaving you.

Size the blast radius first

includeInfo=true on Get a tenant returns subjectCount, objectiveCount, and widgetSessionCount. That is exactly the footprint this endpoint destroys, so read it before you pull the trigger.

Get a tenant

Poll for STATE_ERASING, then NotFound.

Delete a tenant's widget sessions

The narrower cleanup, widget data only.

List tenants

Find the tenant and its counts before erasing.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

id
string
required

Tenant to destroy. Accepts the canonical tenant_… form or the external_id:<value> form.

Response

OK

Tenant is the customer's organization as a readable record rather than an echo. It carries no spec: a tenant is never configured, only asserted, so everything about it lives in the metadata envelope — external_id is the key the customer asserted it under, name is the most recent name they asserted, and updated_at is therefore when the tenant was last asserted.

metadata
object
required

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

state
enum<string>
required
read-only

The current lifecycle state of the tenant. Output only.

Available options:
STATE_UNSPECIFIED,
STATE_ACTIVE,
STATE_ERASING
info
object

TenantInfo provides read-only server-derived data about a tenant.