Platform API

Platform and Runtime Surface

Health probes, feature flags, monitoring, and security report ingestion

These endpoints sit outside the core product controllers and support runtime health, metrics, client telemetry, public feature flags, and security-report ingestion.

Mostly public routesHealth and readinessPrometheus metricsSecurity reports

Authentication and Scope

• All endpoints on this page are public.
• These routes are infrastructure-facing or abuse-detection-facing, not end-user feature APIs.
• User API key creation and management are documented in Authentication API.

Endpoint Reference

Health and Availability

Method	Path	Purpose	Request or query	Auth
GET	/api/	Root app response.	None	Public
GET	/api/health	Liveness probe.	None	Public
GET	/api/healthz	Legacy liveness alias.	None	Public
GET	/api/ready	Readiness probe with DB check.	None	Public

Flags and Monitoring

Method	Path	Purpose	Request or query	Auth
GET	/api/feature-flags	Return the current feature-flag snapshot.	None	Public
GET	/api/monitoring/metrics	Return Prometheus metrics text.	None	Public
GET	/api/monitoring/metrics/json	Return metrics JSON.	None	Public
POST	/api/monitoring/frontend-errors	Ingest frontend error reports.	Body: frontend error payload	Public

Security Reports

Method	Path	Purpose	Request or query	Auth
POST	/api/security/reports/ct	Receive certificate-transparency or similar security reports.	Body: security report payload	Public
POST	/api/security/reports/csp	Receive CSP violation reports.	Body: security report payload	Public

Request Shapes

Frontend error reports

FrontendErrorReportDto

• source: required string, max 180 chars
• message: required string, max 400 chars
• stack: optional string, max 10000 chars
• url: optional string, max 400 chars
• severity: optional error|warn|info
• details: optional object

Security reports

• Security-report endpoints accept the SecurityReportDto payload shape.
• The controller accepts both report and cspReport style payloads.

Example Calls

Read readiness

curl "$PRIMECAL_API/api/ready"

Fetch feature flags

curl "$PRIMECAL_API/api/feature-flags"

Submit a frontend error

curl -X POST "$PRIMECAL_API/api/monitoring/frontend-errors" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "calendar-view",
    "message": "Week view render failed",
    "severity": "error",
    "url": "https://app.primecal.eu/app"
  }'

Response and Behavior Notes

• POST /api/monitoring/frontend-errors returns 202 Accepted.
• Security report endpoints return 204 No Content.
• Feature flags are intentionally public so the frontend can shape pre-login flows.

Best Practices

• Use /api/health and /api/ready for deployment and load-balancer probes, not for customer-facing dashboards.
• Keep frontend error payloads privacy-safe. Do not leak tokens, email addresses, or raw secrets in details.
• Separate observability concerns from product logic in clients. These routes should usually live in platform SDK layers, not feature modules.