Skip to main content
The PlanningSup API provides programmatic access to university calendar data with offline support, authentication, and preferences synchronization.

​
Base URL

All API endpoints are relative to your PlanningSup instance: 
https://planningsup.app/api

​
Authentication

The PlanningSup API supports two authentication methods:

​
No authentication (planning data)

Most endpoints are public and don’t require authentication:
  • /api/plannings - List all available plannings
  • /api/plannings/:fullId - Get planning details and events

​
BetterAuth (user preferences)

When AUTH_ENABLED=true, authentication endpoints are available:
  • /api/auth/* - OAuth login, passkey registration, session management
Authenticated requests include credentials via cookies or bearer tokens.

​
Operations token (admin endpoints)

Admin endpoints require the x-ops-token header: 
curl -H "x-ops-token: YOUR_OPS_TOKEN" \
  https://planningsup.app/api/ops/plannings
In production, OPS_TOKEN must be configured. Without a valid token, operations endpoints return 404.

​
Response format

All responses are JSON with consistent structure.

​
Success response

{
  "id": "elevesing1iereannee",
  "fullId": "enscr.cycleingenieur.1iereanneeci.elevesing1iereannee",
  "title": "Elèves Ing. 1ière année",
  "refreshedAt": 1709419845000,
  "backupUpdatedAt": 1709419800000,
  "status": "ok",
  "source": "network",
  "reason": null,
  "events": [...],
  "nbEvents": 42
}

​
Error response

{
  "error": "Planning not found",
  "message": "..."
}
HTTP status codes indicate the error type:
  • 400 - Bad request (invalid parameters)
  • 404 - Resource not found
  • 429 - Rate limit exceeded
  • 500 - Internal server error

​
Rate limiting

When authentication is enabled, BetterAuth applies rate limits:
  • General endpoints: 100 requests per 60 seconds
  • Passkey endpoints: 5 requests per 10 seconds
Rate-limited responses include a 429 status and may include a Retry-After header.

​
CORS

The API allows cross-origin requests from trusted origins configured via TRUSTED_ORIGINS. For self-hosted instances, configure your frontend origins: 
TRUSTED_ORIGINS=https://your-frontend.com,https://app.your-domain.com

​
API client

For TypeScript projects, use the Eden Treaty client for type-safe requests: 
import { client } from '@libs/client'

// Fully typed request and response
const response = await client.api.plannings.index.get()

if (response.data) {
  // response.data is typed automatically
  console.log(response.data)
}
The client is available in packages/libs/src/client/index.ts.

​
Endpoints

Plannings

List and retrieve university calendar plannings

Events

Fetch calendar events with filtering and timezone support

Authentication

OAuth, passkeys, and session management

Operations

Monitor system health and background jobs

​
Health check

Verify API availability: 
curl https://planningsup.app/api/ping
Response: 
pong
This endpoint is used by Docker health checks and monitoring systems.

​
OpenAPI specification

The API automatically generates OpenAPI documentation from route definitions.
View the OpenAPI spec at /api/openapi (if enabled in your instance).

​
Next steps

Plannings API

Learn how to list and retrieve plannings

Events API

Fetch and filter calendar events

Authentication

Implement user authentication

Operations

Monitor system health

Build docs developers (and LLMs) love

Get started for freeTalk to us