API Reference

The boilerplate exposes a small, stable, documented public API. Every endpoint listed below is shipped, tested, and described programmatically in src/libs/OpenAPI.ts. The same source feeds both this page and the interactive Swagger UI in the dashboard.

Base URL

https://your-domain.example

Local dev defaults to http://localhost:3000. The base URL on the live documentation reflects the value of NEXT_PUBLIC_APP_URL.

Authentication

Two transports are supported, in this order of preference :

• Bearer API key (recommended for machine-to-machine). Send Authorization: Bearer <api-key>. Generate keys from /dashboard/api-keys.
• NextAuth session cookie (browser flows only). The dashboard itself uses this transport.

Forged or unsigned requests are rejected with 401. The 4xx status range is client-side and must not be retried — only 5xx responses are retryable.

Idempotency

Any mutating endpoint accepts an optional Idempotency-Key header. The contract is universal across the API :

• No header → handler runs unchanged.
• Same key + same body → cached response replayed (with response header Idempotency-Replayed: true).
• Same key + different body → 409 Conflict with body { "error": "idempotency_key_request_mismatch" }.
• Cache TTL is 24h. Only 2xx/4xx responses are cached — 5xx replays would mask real outages.

See src/libs/Idempotency.ts for the full implementation.

Errors

Every error payload follows the same envelope :

{
  "error": "Human-readable message.",
  "code": "OPTIONAL_STABLE_CODE"
}

4xx are client-side (don't retry, fix the request). 5xx are server-side (safe to retry with exponential backoff + jitter).

Rate limits

The boilerplate ships with Arcjet wired into the middleware. Default policy in development is unlimited; production deployments are expected to set ARCJET_KEY and tighten the rules in src/middleware.ts. When a request is throttled, the response is 429 Too Many Requests with Retry-After populated.

Endpoints

GET /api/v1/me

Returns the authenticated principal. Accepts Bearer or session-cookie auth.

curl -s https://your-domain.example/api/v1/me \
  -H 'Authorization: Bearer ak_live_xxxxxxxxxxxx'

Response :

{ "id": "usr_...", "email": "user@example.com", "name": "Mo" }

GET /api/health

Public, unauthenticated health probe. Returns 200 healthy/degraded, 503 unhealthy. Cache-Control: no-store.

curl -s https://your-domain.example/api/health

POST /api/inbound/{sourceId}

HMAC-verified inbound webhook receiver. Used to receive events from third-party providers you've registered under /dashboard/webhooks?tab=inbound.

curl -X POST https://your-domain.example/api/inbound/src_xxxxx \
  -H 'Content-Type: application/json' \
  -H 'X-Webhook-Signature: t=1714512345,v1=abcdef0123456789' \
  -H 'X-Webhook-Id: evt_xxxxx' \
  -d '{"id":"evt_xxxxx","type":"invoice.paid","data":{...}}'

The handler always returns within ~10 ms — actual processing happens async via jobs adapter handlers registered with defineInboundHandler({...}).

POST /api/stripe/webhook

Internal — not for public consumption. Stripe webhook handler. Documented here for transparency only. Stripe events are signature-verified against STRIPE_WEBHOOK_SECRET and idempotent on event.id (24h replay window). Forged or unsigned requests get 401.

POST /api/stripe/checkout

Creates a Stripe checkout session for the active user. Requires a NextAuth session — Bearer keys are not yet supported on this route.

curl -X POST https://your-domain.example/api/stripe/checkout \
  -H 'Content-Type: application/json' \
  -b 'authjs.session-token=...' \
  -d '{"tier":"pro","period":"monthly"}'

POST /api/reports/daily

Triggers the daily Discord report. Protected by Authorization: Bearer <CRON_SECRET> when CRON_SECRET is set. Intended for cron schedulers (Vercel Cron, GitHub Actions, etc.).

curl -X POST https://your-domain.example/api/reports/daily \
  -H "Authorization: Bearer $CRON_SECRET"

Try it interactively

Authenticated users can exercise every endpoint in a Swagger UI sandbox at /dashboard/api-docs. The "Try it" button posts real requests to the live deployment, with the user's API key pre-filled where available.

OpenAPI spec

The full machine-readable OpenAPI 3.1 document is available at /api/openapi.json. Paste it into Postman, Insomnia, or your favourite generator to scaffold a typed client in seconds.