API Reference

Base URLs

API endpoints are accessed via subdomain routing:

• Local (direct): http://localhost:3333
• Local (via Caddy): https://api.jubiloop.localhost
• Development: https://dev-api.jubiloop.ca
• QA: https://qa-api.jubiloop.ca
• Production: https://api.jubiloop.ca

Note: Routes are mounted directly without an /api prefix.

Available APIs

Authentication

Session-based authentication with Better Auth integration.

• Authentication API - Sign up, sign in, session management

Events

Event creation and management for organizations.

• Events API - Create, update, and retrieve events

System

Core system endpoints for health monitoring.

• System API - Health checks, status endpoints

Newsletter

Marketing email subscription management.

• Newsletter API - Subscription endpoints

Authentication Method

Jubiloop uses session-based authentication with HTTP-only cookies. After successful login, session cookies are automatically included in subsequent requests.

For protected endpoints, include the session cookie received from the login response.

Response Formats

Application-owned JSON endpoints, including events and newsletter subscription, use the shared response envelope below. The health endpoint returns a health report directly, and /auth/* endpoints use Better Auth's endpoint-specific payloads. Each domain page documents its exact contract.

Success Response

{
  "data": {
    /* Response data */
  },
  "messages": [
    {
      "title": "Operation successful",
      "description": "Optional detailed description"
    }
  ]
}

Error Response

{
  "errors": [
    {
      "message": "Error description",
      "code": "common.server.internal",
      "field": "optionalFieldName",
      "meta": {}
    }
  ]
}

field and meta are optional. code is required for application-owned API errors.

Common HTTP Status Codes

• 200 OK - Request successful
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request data
• 401 Unauthorized - Authentication required
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 422 Unprocessable Entity - Validation errors
• 500 Internal Server Error - Server error
• 503 Service Unavailable - A health check failed

Content Types

• Request: application/json
• Response: application/json

Rate Limiting

Rate limiting is applied to prevent abuse:

• Public endpoints and Better Auth endpoints share a limit of 30 requests per IP address per minute. This includes /health in production mode; non-production health checks are not throttled.
• Protected routes share a limit of 1,000 requests per IP per minute, checked before session lookup. Every request counts, including missing or invalid sessions. This shared ceiling provides headroom for multiple users on the same network; exceeding it returns 429 before authentication.
• After authentication, protected routes also share a limit of 100 requests per user per minute, regardless of the user's IP address. Both the IP and user limits must allow the request.
• Better Auth applies its own endpoint-specific limiter after the route-level throttle
• Rate limiting is disabled in the test environment