Usage API

POST /api/usage/ingest

• Purpose: Ingest usage events from the edge/proxy layer.
• Auth: X-Ingest-Key shared secret.
• Request shape: Usage payload (tenant, declared response bytes, request metadata). Optional timestamp must be an ISO datetime with timezone; it is normalized to UTC for every counter period.
• Response shape: { ok: true, bucket, aggregated: false, counterMode: "atomic", logStatus }. logStatus is stored, sampled-out, or failed.
• Durability: Monthly, daily, hourly, cache, and request-type counters are written atomically before acknowledgement. Sampled logs are awaited separately; a failed log does not undo committed counters.
• Retries: Events are additive and do not yet carry a durable idempotency key. Do not retry after an ambiguous response loss.
• Key errors: 401/403 invalid ingest key, 400 invalid payload.
• Example: POST /api/usage/ingest with ingest key header.

GET /api/usage/check

• Purpose: Internal usage limit/status check.
• Auth: X-Ingest-Key shared secret.
• Request shape: Query for tenant/period (as defined in handler).
• Response shape: Limit/check result.
• Key errors: 401/403, 400.
• Example: GET /api/usage/check?....

GET /api/demos/{provider}

• Purpose: Return demo payload for supported providers.
• Auth: Public read.
• Request shape: Path {provider}.
• Response shape: Demo data for requested provider.
• Key errors: 404 provider not found, 400 invalid provider.
• Example: GET /api/demos/prismic.