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/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/cloudflare-cost

  • Purpose: Legacy partial Cloudflare infrastructure cost estimate for a calendar month; not an invoice or tenant cost ledger. When CF_COST_LIVE_ENABLED=true and the CF Analytics fetch succeeds, returns live-backed numbers; otherwise a modeled fallback. Cached for 10 minutes.
  • Auth: Master admin.
  • Request shape: Optional ?period=YYYY-MM query (defaults to the current calendar month).
  • Response shape: { period, costSource: 'live' | 'modeled', costConfidence, fetchedAt, cacheAgeMs, cost: { workersCost, d1Cost, kvCost, totalCost, ... }, fallbackReason }.
  • Key errors: 400 invalid period, 401, 403.
  • Example: GET /api/admin/cloudflare-cost?period=2026-04.

GET /api/admin/infrastructure-cost

  • Purpose: Read the latest persisted Cloudflare billing snapshot with account/day totals, estimated tenant attribution, meter coverage, resource classification and invoice reconciliation. If no snapshot exists, collect and save one first. Missing amounts remain unknown, not zero.
  • Auth: Master admin.
  • Request shape: Optional ?period=YYYY-MM naming the month in which the billing cycle starts (defaults to the current cycle; configured anchor is the 5th, UTC).
  • Response shape: { ok: true, report }, including days, tenants, totals, reconciliation, warnings and freshness information. Tenant allocations are estimates; external projects, shared fees and unallocated usage remain separate.
  • Key errors: 400 invalid period, 401, 403, 502 unavailable cost data, 503 invalid billing-day configuration.
  • Example: GET /api/admin/infrastructure-cost?period=2026-09.

POST /api/admin/infrastructure-cost-sync

  • Purpose: Fetch and persist a new provider snapshot for a billing cycle. Failed refreshes preserve the last saved report and record the failure for freshness reporting.
  • Auth: Master admin.
  • Request shape: Optional body { "period": "2026-09" }; defaults to the current billing cycle.
  • Response shape: { ok: true }. Read the report with GET /api/admin/infrastructure-cost.
  • Key errors: 400 invalid period, 401, 403, 502 provider sync failure.
  • Example: POST /api/admin/infrastructure-cost-sync with body { "period": "2026-09" }.

POST /api/admin/infrastructure-cost-rule

  • Purpose: Save account-scoped resource attribution. Updates retain previous and new values in the cost audit log.
  • Auth: Master admin.
  • Request shape: { resource, scope, label }; resource uses a worker:, kv:, r2:, d1:, do: or queue: prefix; scope is cachely, external or shared.
  • Response shape: { ok: true }.
  • Key errors: 400 invalid classification, 401, 403, 500 persistence failure.
  • Example: POST /api/admin/infrastructure-cost-rule with body { "resource": "worker:another-project", "scope": "external", "label": "Separate project" }.

POST /api/admin/infrastructure-cost-evidence

  • Purpose: Save reviewed invoice line totals after verifying their sum and currency against an actual Cloudflare invoice. Provider-versus-invoice usage differences remain visible; updates are audited.
  • Auth: Master admin.
  • Request shape: { invoiceId, number, period, currency, usage, fixed, adjustments, source }. Amounts use exact currency cents; period is the usage cycle, and fixed is the nonnegative prepaid fee for the following cycle. source identifies the reviewed document.
  • Response shape: { ok: true }.
  • Key errors: 400 invalid evidence or invoice mismatch, 401, 403, 500 provider/persistence failure.
  • Example: Submit the selected invoice ID/number with its reviewed usage, prepaid fixed fee, adjustments and source filename from the master-admin cost form.

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/usage-aggregator-status

  • Purpose: Telemetry snapshot for the in-process usage write-behind aggregator and the threshold-check gate. Use for incident debugging ("is the feature flag on?", "when did we last flush?", "how many logs were dropped by sampling?"). No D1 reads — entirely in-memory.
  • Auth: Master admin.
  • Request shape: No query params.
  • Response shape: { generatedAt, aggregator: { enabled, flushIntervalMs, flushMaxEntries, requestLogSampleRate, enqueuedDeltas, droppedWhenDisabled, sampledLogs, skippedLogs, flushes, flushErrors, lastFlushAt, lastFlushDurationMs, lastFlushBucketCount, lastFlushLogCount, lastError, pendingBuckets, pendingLogs, prunes, lastPruneAt, lastPruneRowsDeleted }, thresholdGate: { enabled, intervalMs, allowed, skippedThrottled, skippedDisabled, evictedEntries, trackedOrgs } }.
  • Key errors: 401, 403.
  • Example: GET /api/admin/usage-aggregator-status.

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/prune-logs

  • Purpose: Manually sweep request_logs older than the retention window. Complements the aggregator's opportunistic prune — use from an external cron (Github Actions, uptime pinger) if you want a fixed cadence.
  • Auth: Master admin.
  • Request shape: Optional body { retentionDays?: number } (defaults to the repository's PRUNE_THRESHOLD_DAYS).
  • Response shape: { ok, deleted } where deleted is the row count removed.
  • Key errors: 401, 403, 500 DB errors.
  • Example: POST /api/admin/prune-logs with body { "retentionDays": 30 }.

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.

PATCH /api/admin/billing/{orgId}

  • Purpose: Override the billing plan for a specific org/user. Sets an admin override flag so Stripe webhooks will not revert the change.
  • Auth: Master admin.
  • Request shape: Body { planCode: "free" | "pro" }.
  • Response shape: { ok, billing }.
  • Key errors: 400 invalid planCode, 401, 403.
  • Example: PATCH /api/admin/billing/user_123 with body { "planCode": "pro" }.

POST /api/admin/quota-snapshots/backfill

  • Purpose: Master-admin-only, idempotent. Publishes a quota:{orgId} edge quota snapshot for every known org so the proxy worker has a snapshot to read for each org before EDGE_QUOTA_ENABLED is flipped on. Safe to re-run — publishQuotaSnapshot overwrites and never throws.
  • Auth: Master admin.
  • Request shape: none.
  • Response shape: { ok, orgs, processed } where orgs is the total count of distinct org IDs found and processed is the number successfully iterated.
  • Key errors: 401, 403.
  • Example: POST /api/admin/quota-snapshots/backfill.

POST /api/admin/backfill-members

  • Purpose: One-time migration that seeds tenant_members rows from tenants.created_by. Safe to call multiple times (uses INSERT OR IGNORE).
  • Auth: Master admin.
  • Request shape: none.
  • Response shape: { ok, seeded }.
  • Key errors: 401, 403.
  • Example: POST /api/admin/backfill-members.
✦
Need help understanding this?Ask Cachely Copilot about features, setup, or integrations.
Ask Copilot →