Tenants

Sintesis supports users with membership in multiple tenants. The active tenant is stored in a session cookie and determines which data is visible across all other API endpoints.

Switch active tenant

POST /api/tenants/{tenantId}/switch

string

Sets the active tenant for the current session. The user must be a member of the target tenant, or be a superadmin. On success, the response sets the active_tenant_id cookie (30-day expiry) and returns { "success": true }.

Path parameters

tenantId

string

required

UUID of the tenant to activate. Must be a valid UUID v4 format.

Response

success

boolean

required

Always true on success.

Error responses

Status	Condition
`400`	`tenantId` is missing or not a valid UUID.
`401`	Not authenticated.
`403`	User is not a member of the specified tenant and is not a superadmin.

Request
Response

curl -X POST 'https://<domain>/api/tenants/target-tenant-uuid-.../switch' \
  --cookie 'sb-access-token=<session>'

{ "success": true }

Switch active tenant (redirect)

GET /api/tenants/{tenantId}/switch

string

Sets the active tenant and redirects the browser to /excel. Designed for use in navigation links rather than programmatic API calls.

If the user is not authenticated, redirects to /.
If the user is not a member of the tenant and is not a superadmin, redirects to /onboarding.
On success, sets the active_tenant_id cookie and redirects to /excel.

Path parameters

tenantId

string

required

UUID of the tenant to activate.

Get tenant usage

GET /api/tenant-usage

string

Returns the current plan and usage counters for the authenticated user’s active tenant.

Response

tenantId

string

required

Active tenant UUID.

plan

object

required

The tenant’s subscription plan.

Show Plan properties

name

string

Plan name.

limits

object

Usage limits for the plan.

Show Limit properties

storageBytes

number

Maximum storage in bytes.

aiTokens

number

Maximum AI token usage.

whatsappMessages

number

Maximum WhatsApp messages.

usage

object

required

Current usage counters.

Show Usage properties

storageBytes

number

Current storage used in bytes.

aiTokens

number

Current AI tokens consumed.

whatsappMessages

number

Current WhatsApp messages sent.

Request
Response

curl 'https://<domain>/api/tenant-usage' \
  --cookie 'sb-access-token=<session>'

{
  "tenantId": "tenant-uuid-...",
  "plan": {
    "name": "Growth",
    "limits": {
      "storageBytes": null,
      "aiTokens": null,
      "whatsappMessages": null
    }
  },
  "usage": {
    "storageBytes": 524288000,
    "aiTokens": 12340,
    "whatsappMessages": 7
  }
}

Increment tenant usage

POST /api/tenant-usage

string

Applies a usage delta to the tenant’s current counters. Used internally by background jobs and server actions that consume metered resources.

If the updated value would exceed any plan limit, the endpoint returns 402 Payment Required and the counter is not incremented.

Request body

storageBytesDelta

number

Bytes to add (positive) or remove (negative) from storage usage.

aiTokensDelta

number

AI tokens to add to usage.

whatsappMessagesDelta

number

WhatsApp messages to add to usage.

reason

string

Optional human-readable reason for the adjustment (logged in usage event history).

metadata

object

Optional metadata object logged with the usage event.

At least one delta field must be non-zero.

Response

boolean

required

Always true on success.

plan

object

required

Updated plan object (same structure as GET response).

usage

object

required

Updated usage counters (same structure as GET response).

Error responses

Status	Error code	Description
`400`	—	No delta fields provided or values are not finite numbers.
`402`	`storage_limit_exceeded`	Storage limit would be exceeded.
`402`	`ai_limit_exceeded`	AI token limit would be exceeded.
`402`	`whatsapp_limit_exceeded`	WhatsApp message limit would be exceeded.
`403`	`insufficient_privilege`	The operation is not permitted for this user’s role.

Request
Response

curl -X POST 'https://<domain>/api/tenant-usage' \
  --cookie 'sb-access-token=<session>' \
  --header 'Content-Type: application/json' \
  --data '{
    "storageBytesDelta": 2097152,
    "reason": "document_upload",
    "metadata": { "fileId": "doc-uuid-..." }
  }'

{
  "ok": true,
  "plan": { "name": "Growth", "limits": { "storageBytes": null, "aiTokens": null, "whatsappMessages": null } },
  "usage": { "storageBytes": 526385152, "aiTokens": 12340, "whatsappMessages": 7 }
}

API Endpoints

Switch active tenant

Path parameters

Response

Error responses

Switch active tenant (redirect)

Path parameters

Get tenant usage

Response

Increment tenant usage

Request body

Response

Error responses

Build docs developers (and LLMs) love

API Endpoints

​Switch active tenant

​Path parameters

​Response

​Error responses

​Switch active tenant (redirect)

​Path parameters

​Get tenant usage

​Response

​Increment tenant usage

​Request body

​Response

​Error responses

Build docs developers (and LLMs) love

Switch active tenant

Path parameters

Response

Error responses

Switch active tenant (redirect)

Path parameters

Get tenant usage

Response

Increment tenant usage

Request body

Response

Error responses