Admin API

GET /api/admin/overview

• Purpose: Global admin overview metrics.
• Auth: Master admin.
• Request shape: Optional period/filter query.
• Response shape: Aggregated platform metrics.
• Key errors: 401, 403.
• Example: GET /api/admin/overview.

GET /api/admin/my-overview

• Purpose: Overview tied to the currently authenticated admin user.
• Auth: Admin session.
• Request shape: Optional query filters.
• Response shape: Dashboard summary.
• Key errors: 401, 403.
• Example: GET /api/admin/my-overview.

GET /api/admin/my-daily

• Purpose: Daily metrics series for the current admin user.
• Auth: Admin session.
• Request shape: Query period/range.
• Response shape: Daily points.
• Key errors: 400, 401, 403.
• Example: GET /api/admin/my-daily.

GET /api/admin/bandwidth-daily

• Purpose: Global daily bandwidth aggregates.
• Auth: Master admin.
• Request shape: Query period/range.
• Response shape: List of daily bandwidth values.
• Key errors: 400, 401, 403.
• Example: GET /api/admin/bandwidth-daily.

GET /api/admin/usage-stream

• Purpose: Stream/near-real-time usage feed for admin views.
• Auth: Master admin.
• Request shape: Optional cursor/limit query.
• Response shape: Stream items + metadata.
• Key errors: 401, 403.
• Example: GET /api/admin/usage-stream.

GET /api/admin/usage-diagnostic

• Purpose: Usage pipeline diagnostics.
• Auth: Master admin.
• Request shape: Optional diagnostics query.
• Response shape: Health/diagnostic data.
• Key errors: 401, 403.
• Example: GET /api/admin/usage-diagnostic.

GET /api/admin/logs

• Purpose: Platform request/error log listing.
• Auth: Master admin.
• Request shape: Query filters (cursor, limit, level, etc).
• Response shape: Log entries + pagination.
• Key errors: 400, 401, 403.
• Example: GET /api/admin/logs.

POST /api/admin/logs-test

• Purpose: Test endpoint for log pipeline.
• Auth: Master admin.
• Request shape: Optional test payload.
• Response shape: { ok } + test metadata.
• Key errors: 401, 403.
• Example: POST /api/admin/logs-test.

POST /api/admin/d1-init

• Purpose: Initialize D1 structures/tables.
• Auth: Master admin.
• Request shape: none.
• Response shape: Init result.
• Key errors: 401, 403, 500 DB errors.
• Example: POST /api/admin/d1-init.

POST /api/admin/migrate-kv-to-d1

• Purpose: Migrate data from KV to D1.
• Auth: Master admin.
• Request shape: Optional migration parameters.
• Response shape: Migration report.
• Key errors: 401, 403, 500.
• Example: POST /api/admin/migrate-kv-to-d1.

GET /api/admin/tenants/{slug}/earned

• Purpose: Billing/earnings overview for a tenant.
• Auth: Master admin.
• Request shape: Path {slug} + optional period.
• Response shape: Earnings summary.
• Key errors: 404, 401, 403.
• Example: GET /api/admin/tenants/acme/earned.

GET /api/admin/users/{userId}

• Purpose: Read details for an admin user record.
• Auth: Master admin.
• Request shape: Path {userId}.
• Response shape: User admin view model.
• Key errors: 404, 401, 403.
• Example: GET /api/admin/users/user_123.

PATCH /api/admin/users/{userId}

• Purpose: Partial update of admin user state.
• Auth: Master admin.
• Request shape: Path {userId} + patch body.
• Response shape: Updated user model.
• Key errors: 400, 404, 401, 403.
• Example: PATCH /api/admin/users/user_123.

GET /api/admin/users/{userId}/daily

• Purpose: Daily metrics for a specific user.
• Auth: Master admin.
• Request shape: Path {userId} + period query.
• Response shape: Daily usage series.
• Key errors: 400, 404, 401, 403.
• Example: GET /api/admin/users/user_123/daily.

POST /api/admin/users/{userId}/block

• Purpose: Block/unblock a user according to policy.
• Auth: Master admin.
• Request shape: Path {userId} + block payload.
• Response shape: { ok } + updated status.
• Key errors: 400, 404, 401, 403.
• Example: POST /api/admin/users/user_123/block.

POST /api/admin/users/{userId}/reset-password

• Purpose: Trigger admin password reset for a user.
• Auth: Master admin.
• Request shape: Path {userId} + reset payload (if applicable).
• Response shape: { ok }.
• Key errors: 404, 401, 403.
• Example: POST /api/admin/users/user_123/reset-password.