Skip to main content
A tenant is the top-level organizational unit in Knowledge Stack. Every resource — folders, documents, groups, and users — belongs to a tenant.

​
List tenants

Returns all tenants that the authenticated user belongs to. 
GET https://api-staging.knowledgestack.ai/v1/tenants
​
page
integer
Page number (1-indexed). Defaults to 1.
​
page_size
integer
Number of results per page. Defaults to 20.
Example 
curl https://api-staging.knowledgestack.ai/v1/tenants \
  -H "Authorization: Bearer <your-api-key>"
Response — PaginatedResponse[TenantResponse] 
{
  "items": [
    {
      "id": "a1b2c3d4-...",
      "name": "Acme Corp",
      "settings": {
        "language": "en",
        "description": "Acme Corp tenant",
        "timezone": "America/New_York"
      },
      "branding": {
        "brand_name": "Acme",
        "brand_color": "#2563eb",
        "logo_url": "https://...",
        "logo_dark_url": null,
        "favicon_url": null,
        "theme_overrides": null
      }
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

​
Get tenant

Returns details for a single tenant. 
GET https://api-staging.knowledgestack.ai/v1/tenants/{tenant_id}
​
tenant_id
string
required
UUID of the tenant.
Example 
curl https://api-staging.knowledgestack.ai/v1/tenants/a1b2c3d4-e5f6-... \
  -H "Authorization: Bearer <your-api-key>"
Response — TenantResponse
​
id
string
UUID of the tenant.
​
name
string
Display name of the tenant.
​
settings
object
User-configurable settings for the tenant.
​
branding
object
Tenant branding configuration including logo URLs.

​
Update tenant

Partially updates a tenant’s name or settings. All fields are optional — omit fields you don’t want to change. 
PATCH https://api-staging.knowledgestack.ai/v1/tenants/{tenant_id}
​
tenant_id
string
required
UUID of the tenant.
​
name
string
New display name for the tenant.
​
settings
object
Tenant settings to update. All sub-fields are optional.
Example 
curl -X PATCH https://api-staging.knowledgestack.ai/v1/tenants/a1b2c3d4-e5f6-... \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp (Updated)", "settings": {"timezone": "Europe/London"}}'
Response — TenantResponse

​
Delete tenant

Permanently deletes a tenant and all associated resources. 
DELETE https://api-staging.knowledgestack.ai/v1/tenants/{tenant_id}
​
tenant_id
string
required
UUID of the tenant.
This action is irreversible. All tenant data — including documents, folders, users, and groups — is permanently deleted.
Example 
curl -X DELETE https://api-staging.knowledgestack.ai/v1/tenants/a1b2c3d4-e5f6-... \
  -H "Authorization: Bearer <your-api-key>"

​
List tenant users

Returns all users belonging to the specified tenant. 
GET https://api-staging.knowledgestack.ai/v1/tenants/{tenant_id}/users
​
tenant_id
string
required
UUID of the tenant.
​
page
integer
Page number (1-indexed).
​
page_size
integer
Number of results per page.
Example 
curl https://api-staging.knowledgestack.ai/v1/tenants/a1b2c3d4-e5f6-.../users \
  -H "Authorization: Bearer <your-api-key>"
Response — PaginatedResponse[TenantUserResponse]
​
user_id
string
UUID of the user.
​
email
string | null
User’s email address.
​
first_name
string | null
User’s first name.
​
last_name
string | null
User’s last name.
​
role
string
The user’s role within this tenant. One of USER, ADMIN, OWNER.
​
is_tenant_idp_managed
boolean
Whether the user’s account is managed by the tenant’s identity provider.
​
deactivated_on
string | null
ISO 8601 timestamp when the user was deactivated. null means the user is active.
​
created_at
string
ISO 8601 timestamp when the user joined the tenant.
​
updated_at
string
ISO 8601 timestamp of the last update to this membership record.

​
Activate user

Re-activates a previously deactivated user, restoring their access to the tenant. 
POST https://api-staging.knowledgestack.ai/v1/tenants/{tenant_id}/users/{user_id}/activate
​
tenant_id
string
required
UUID of the tenant.
​
user_id
string
required
UUID of the user to activate.
Example 
curl -X POST https://api-staging.knowledgestack.ai/v1/tenants/a1b2c3d4-.../users/u1u2u3u4-.../activate \
  -H "Authorization: Bearer <your-api-key>"

​
Deactivate user

Deactivates a user, preventing them from accessing the tenant without permanently removing them. 
POST https://api-staging.knowledgestack.ai/v1/tenants/{tenant_id}/users/{user_id}/deactivate
​
tenant_id
string
required
UUID of the tenant.
​
user_id
string
required
UUID of the user to deactivate.
Example 
curl -X POST https://api-staging.knowledgestack.ai/v1/tenants/a1b2c3d4-.../users/u1u2u3u4-.../deactivate \
  -H "Authorization: Bearer <your-api-key>"

​
Remove user from tenant

Permanently removes a user from the tenant. The user’s account is not deleted, but they lose all access to this tenant. 
DELETE https://api-staging.knowledgestack.ai/v1/tenants/{tenant_id}/users/{user_id}
​
tenant_id
string
required
UUID of the tenant.
​
user_id
string
required
UUID of the user to remove.
Example 
curl -X DELETE https://api-staging.knowledgestack.ai/v1/tenants/a1b2c3d4-.../users/u1u2u3u4-... \
  -H "Authorization: Bearer <your-api-key>"

​
Update user role

Changes a user’s role within the tenant. 
PATCH https://api-staging.knowledgestack.ai/v1/tenants/{tenant_id}/users/{user_id}
​
tenant_id
string
required
UUID of the tenant.
​
user_id
string
required
UUID of the user whose role you want to update.
​
role
string
required
New role for the user. One of USER, ADMIN, OWNER.
TenantUserRole values
ValueDescription
USERStandard member. Access is governed by permissions.
ADMINCan manage users, groups, and tenant settings.
OWNERFull control, including deleting the tenant.
Example 
curl -X PATCH https://api-staging.knowledgestack.ai/v1/tenants/a1b2c3d4-.../users/u1u2u3u4-... \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"role": "ADMIN"}'
Uploads a logo image for the tenant. Use the logo_type field to specify whether you’re uploading the primary logo, a dark-mode logo, or the favicon. 
POST https://api-staging.knowledgestack.ai/v1/tenants/{tenant_id}/branding/logo
This endpoint accepts multipart/form-data. Do not set Content-Type manually — your HTTP client will set the correct boundary automatically.
​
tenant_id
string
required
UUID of the tenant.
​
file
file
required
The image file to upload (PNG, JPEG, SVG, or ICO).
​
logo_type
string
required
Which logo slot to populate. One of:
  • logo — primary light-mode logo
  • logo_dark — dark-mode logo variant
  • favicon — browser tab icon
Example 
curl -X POST https://api-staging.knowledgestack.ai/v1/tenants/a1b2c3d4-e5f6-.../branding/logo \
  -H "Authorization: Bearer <your-api-key>" \
  -F "file=@/path/to/logo.png" \
  -F "logo_type=logo"
Removes a previously uploaded logo from the tenant’s branding configuration. 
DELETE https://api-staging.knowledgestack.ai/v1/tenants/{tenant_id}/branding/logo
​
tenant_id
string
required
UUID of the tenant.
​
logo_type
string
required
Which logo to delete. One of logo, logo_dark, favicon.
Example 
curl -X DELETE "https://api-staging.knowledgestack.ai/v1/tenants/a1b2c3d4-e5f6-.../branding/logo?logo_type=logo" \
  -H "Authorization: Bearer <your-api-key>"