Tenants API

All endpoints below use the same docs format and reference Zod/TS shapes from server code.

GET /api/tenants

• Purpose: List tenants for the authenticated user.
• Auth: Clerk session.
• Request shape: none.
• Response shape: { total, tenants[] }.
• Key errors: 401 unauthorized.
• Example: GET /api/tenants.

POST /api/tenants

• Purpose: Create a new tenant.
• Auth: Clerk session.
• Request shape: Slug + CMS configuration + optional cache/domain fields.
• Response shape: { ok, key, proxyBase }.
• Key errors: 403 plan limit, 409 slug already used, 400 validation.
• Example: Body with slug, cms, and provider-specific fields.

GET /api/tenants/slug-availability

• Purpose: Check whether a slug is available.
• Auth: Clerk session.
• Request shape: Query slug.
• Response shape: { slug, available }.
• Key errors: 400 invalid slug.
• Example: GET /api/tenants/slug-availability?slug=my-project.

GET /api/tenants/usage

• Purpose: Aggregate usage across all user tenants.
• Auth: Clerk session.
• Request shape: Optional period query.
• Response shape: Per-tenant list/aggregates.
• Key errors: 401.
• Example: GET /api/tenants/usage.

GET /api/tenants/{slug}

• Purpose: Read configuration for a single tenant.
• Auth: Clerk session + tenant access.
• Request shape: Path {slug}.
• Response shape: { key, value }.
• Key errors: 404 tenant not found.
• Example: GET /api/tenants/acme.

PUT /api/tenants/{slug}

• Purpose: Update tenant configuration (partial update).
• Auth: Clerk session + tenant access.
• Request shape: Body with changed fields (Zod validation).
• Response shape: Updated { key, value }.
• Key errors: 400 invalid body, 404 tenant not found.
• Example: Body { cacheTTL, websiteDomain }.

DELETE /api/tenants/{slug}

• Purpose: Delete a tenant and related configuration.
• Auth: Clerk session + tenant access.
• Request shape: Path {slug}.
• Response shape: { ok, key }.
• Key errors: 404 tenant not found.
• Example: DELETE /api/tenants/acme.

GET /api/tenants/{slug}/analytics

• Purpose: Return tenant analytics overview.
• Auth: Clerk session + tenant access.
• Request shape: Path {slug} + optional period query.
• Response shape: Analytics object for dashboards.
• Key errors: 404, 400 invalid period.
• Example: GET /api/tenants/acme/analytics.

GET /api/tenants/{slug}/bandwidth-daily

• Purpose: Daily bandwidth breakdown for a tenant.
• Auth: Clerk session + tenant access.
• Request shape: Path {slug} + optional range query.
• Response shape: Daily usage points.
• Key errors: 400 invalid range, 404.
• Example: GET /api/tenants/acme/bandwidth-daily.

GET /api/tenants/{slug}/domains

• Purpose: List custom domain records for a tenant.
• Auth: Clerk session + tenant access.
• Request shape: Path {slug}.
• Response shape: Domain list with statuses.
• Key errors: 404.
• Example: GET /api/tenants/acme/domains.

POST /api/tenants/{slug}/domains

• Purpose: Add a custom domain to a tenant.
• Auth: Clerk session + tenant access.
• Request shape: Body with hostname field.
• Response shape: Created domain record.
• Key errors: 400 invalid hostname, 409 already exists.
• Example: Body { hostname: \"cdn.acme.com\" }.

DELETE /api/tenants/{slug}/domains

• Purpose: Remove a custom domain from a tenant.
• Auth: Clerk session + tenant access.
• Request shape: Path {slug} + body/query identifying the domain to remove.
• Response shape: { ok }.
• Key errors: 404 domain not found.
• Example: DELETE /api/tenants/acme/domains.

POST /api/tenants/{slug}/domains/verify

• Purpose: Trigger/check custom domain DNS verification.
• Auth: Clerk session + tenant access.
• Request shape: Path {slug} + domain identifier.
• Response shape: Domain verification status.
• Key errors: 400, 404.
• Example: POST /api/tenants/acme/domains/verify.

GET /api/tenants/{slug}/logs

• Purpose: Tenant-level request log view.
• Auth: Clerk session + tenant access.
• Request shape: Path {slug} + pagination/filter query.
• Response shape: Log entries + pagination metadata.
• Key errors: 400 invalid query, 404.
• Example: GET /api/tenants/acme/logs.

POST /api/tenants/{slug}/refresh-cache

• Purpose: Increment cache versions and force new cache keys.
• Auth: Clerk session + tenant access (editor+).
• Request shape: Body with type (api, assets, html, all).
• Response shape: { ok, versions: { apiCacheVersion, assetCacheVersion, htmlCacheVersion } }.
• Key errors: 400 invalid type, 403 insufficient role.
• Example: Body { type: \"html\" }.

POST /api/tenants/{slug}/webhook

• Purpose: External webhook endpoint for CMS publish notifications (e.g. Webflow site_publish). Bumps htmlCacheVersion so the edge Worker fetches fresh HTML on the next request.
• Auth: Per-tenant URL-embedded secret (?secret=). No Clerk session required.
• Request shape: Query secret. Body is ignored (compatible with any CMS webhook payload).
• Response shape: { ok, htmlCacheVersion }.
• Key errors: 401 missing or invalid secret, 403 webhook not configured, 404 unknown project.
• Example: POST /api/tenants/acme/webhook?secret=abc123....

POST /api/tenants/{slug}/webhook-secret

• Purpose: Generate a webhook secret for the tenant (idempotent — returns existing secret if already generated).
• Auth: Clerk session + tenant access (editor+).
• Request shape: none.
• Response shape: { secret }.
• Key errors: 403 insufficient role, 404 tenant not found.
• Example: POST /api/tenants/acme/webhook-secret.

PUT /api/tenants/{slug}/webhook-secret

• Purpose: Rotate the webhook secret. The old secret becomes invalid immediately.
• Auth: Clerk session + tenant access (admin+).
• Request shape: none.
• Response shape: { secret }.
• Key errors: 403 insufficient role, 404 tenant not found.
• Example: PUT /api/tenants/acme/webhook-secret.

PUT /api/tenants/{slug}/api-config

• Purpose: Save API proxy configuration without token.
• Auth: Clerk session + tenant access.
• Request shape: Body with apiOrigin, auth mode, TTL, and preview/cache options.
• Response shape: Saved API config.
• Key errors: 400 validation, 404.
• Example: Body with apiOrigin and apiAuthMode.

PUT /api/tenants/{slug}/api-token

• Purpose: Write-only save of encrypted API token.
• Auth: Clerk session + tenant access.
• Request shape: Body { token }.
• Response shape: { ok, updatedAt }.
• Key errors: 400 token missing, 404.
• Example: Body { token: \"***\" }.

GET /api/tenants/{slug}/usage

• Purpose: Usage overview for a single tenant.
• Auth: Clerk session + tenant access.
• Request shape: Path {slug} + optional period.
• Response shape: { current, previous, period }.
• Key errors: 404, 400 invalid period.
• Example: GET /api/tenants/acme/usage.

GET /api/tenants/{slug}/members

• Purpose: List all members for a tenant. Pending invites (with PII) are only included for admins and owners.
• Auth: Clerk session + tenant membership (viewer+).
• Request shape: Path {slug}.
• Response shape: { members[], invites[] }. invites is empty for non-admin callers.
• Key errors: 401, 403, 404 tenant not found.
• Example: GET /api/tenants/acme/members.

POST /api/tenants/{slug}/members/invite

• Purpose: Create or refresh an invite for a new member. Requires admin role. Admins cannot assign the owner role.
• Auth: Clerk session + tenant admin+.
• Request shape: Path {slug} + body { email: string, role: "viewer"|"editor"|"admin"|"owner" }.
• Response shape: { id, email, role, token, expiresAt, createdAt, emailSent }.
• Key errors: 400 validation, 403 insufficient privileges or role escalation, 404 tenant not found.
• Example: Body { email: "user@example.com", role: "editor" }.

POST /api/tenants/{slug}/members/remove

• Purpose: Remove a member from the tenant. Cannot remove yourself, the last owner, or someone with equal/higher privileges (unless owner).
• Auth: Clerk session + tenant admin+.
• Request shape: Path {slug} + body { userId: string }.
• Response shape: { ok, userId }.
• Key errors: 400 validation, 403 self-removal or privilege check, 404 member not found.
• Example: Body { userId: "user_123" }.

POST /api/tenants/{slug}/members/revoke-invite

• Purpose: Revoke a pending invite by its ID.
• Auth: Clerk session + tenant admin+.
• Request shape: Path {slug} + body { inviteId: number }.
• Response shape: { ok, inviteId }.
• Key errors: 400 validation, 403, 404 invite not found or already revoked.
• Example: Body { inviteId: 42 }.

POST /api/tenants/{slug}/members/update-role

• Purpose: Change a member's role. Cannot change your own role, assign owner (unless caller is owner), or act on members with equal/higher privileges.
• Auth: Clerk session + tenant admin+.
• Request shape: Path {slug} + body { userId: string, role: "viewer"|"editor"|"admin"|"owner" }.
• Response shape: { userId, role, updatedAt }.
• Key errors: 400 validation, 403 privilege checks, 404 member not found.
• Example: Body { userId: "user_123", role: "admin" }.