API Overview

PrimeCal API Reference

The Non-Admin API Map

This reference is built directly from the backend controllers and DTOs. It documents the user-facing and integration-facing API surface and intentionally excludes the admin controllers and admin-only routes.

Base path: /apiJWT, cookie, API key, and agent authCode-backed DTO constraintsAdmin surface excluded

Scope

• Included: non-admin controllers and non-admin product routes
• Excluded: /api/admin/* controllers and non-/admin routes that are protected with AdminGuard
• Source of truth: NestJS controllers, DTOs, and guard behavior in backend-nestjs/src

Base URL and Auth Model

Topic	Notes
Base path	All examples assume /api
Swagger UI	Generated Swagger can be served at /api/docs when enabled
Browser sessions	Use refresh cookies plus CSRF for mutating requests
Bearer auth	Authorization: Bearer <token>
User API keys	Supported on routes guarded by JwtAuthGuard; send x-api-key or Authorization: ApiKey <token>
Agent keys	Required for MCP runtime; send x-agent-key, x-agent-token, or Authorization: Agent <token>

Product-Area Reference Map

Page	Product area	Highlights
Authentication API	Authentication	register, login, onboarding, MFA, OAuth, user API keys
User API	User and profile	profile settings, language, permissions, user search
Personal Logs API	Personal logs	audit feed and summary
Compliance API	Privacy and compliance	exports, requests, consents, policy acceptance
Calendar API	Calendar	calendars, groups, sharing
Event API	Events	event CRUD, recurrence, comments
Tasks API	Tasks	tasks, labels, filtering
Automation API	Automation	rules, audit logs, approvals, webhook trigger
External Sync API	External sync	provider status, OAuth, mappings, force sync
Agent API	AI agents and MCP	agents, scopes, keys, MCP runtime
Notifications API	Notifications	inbox, preferences, rules, mutes, threads
Organization API	Organizations	membership, roles, color, deletion preview
Resource API	Resources	resource types, resources, public tokens
Booking API	Reservations and public booking	reservation calendars, reservations, public booking
Platform API	Platform	health, flags, metrics, security reports

Quick Start Examples

Bearer auth

export PRIMECAL_API=https://api.primecal.eu
curl "$PRIMECAL_API/api/calendars" \
  -H "Authorization: Bearer $TOKEN"

User API key

curl "$PRIMECAL_API/api/tasks" \
  -H "Authorization: ApiKey $USER_API_KEY"

Agent key

curl "$PRIMECAL_API/api/mcp/actions" \
  -H "Authorization: Agent $AGENT_KEY"

Best Practices

• Group client code by product area, not just by controller path.
• Use the DTO constraints in these pages as your request-contract source of truth.
• Treat admin-only routes as a separate documentation surface.
• Build integration UIs from live catalog endpoints where they exist, such as automation smart values or the agent catalog.