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.
• Request shape: Body with type (api, assets, all).
• Response shape: { ok, versions }.
• Key errors: 400 invalid type.
• Example: Body { type: \"all\" }.

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.