Skip to main content
GET
JavaScript
You never create a tenant. One appears the first time you assert it: on an objective, or when you mint a widget session. This list is the census of what those assertions have produced.

A tenant is a record, not a configuration

There is no spec on a tenant, because there is nothing to configure. Everything lives in the metadata envelope: external_id is the key you asserted it under, name is the most recent name you asserted, and updated_at is when you last asserted it. Assert a new name and the record updates in place.

info costs extra, so ask for it

includeInfo=true populates three counts per tenant: subjectCount, objectiveCount, and widgetSessionCount. objectiveCount spans every surface, widget conversations and direct API objectives alike, so it is the footprint an erase would destroy. Each count is a query per tenant, which is why the field stays empty unless you ask.

Filtering

query does a substring match against each tenant’s name and external_id. It exists for type-ahead pickers, where the operator knows the customer’s own identifier rather than Cadenya’s. labels filters by metadata labels with AND semantics (env=prod,team=ai). sortOrder, limit, and cursor page the list the usual way; the SDK iterators follow the cursor for you.

Get a tenant

Fetch one by canonical ID or external_id: form.

List a tenant's subjects

The people asserted under each tenant.

Erase a tenant

Destroy everything the counts describe.

Create a widget session

One of the two places a tenant gets asserted.

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"

Query Parameters

limit
integer<int32>

Maximum number of results to return.

cursor
string

Pagination cursor from previous response.

query
string

Substring match against the tenant's name and external_id. Built for type-ahead filter pickers, where the operator knows the customer's own identifier rather than Cadenya's.

labels
string

Filters by metadata labels. Comma-separated key=value pairs, e.g. "env=prod,team=ai". A resource matches only if every pair matches exactly (AND semantics).

sortOrder
string

Sort order for results (asc or desc by creation time).

includeInfo
boolean

When true, the info field on each returned tenant is populated. This costs several count queries per tenant, so it is off by default.

Response

OK

List tenants response.

items
object[]
pagination
object

Page carries cursor-based pagination state. There is no total: the cursor walks the result set without ever counting it, and a count would cost a second query on every list.