API Overview - Whilst

The Whilst API is a RESTful API built with Next.js 14 App Router. All endpoints are under /api.

Base URLs

Environment	URL
Local	`http://127.0.0.1:3000/api`
Staging	`https://api.staging.whilst.app`
Production	`https://api.whilst.app`

Response Format

All endpoints return JSON. Successful responses include the data directly. Errors follow a consistent structure:

{
  "message": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "details": {}
}

Authentication

Most endpoints require authentication via session cookies. After logging in through WorkOS, a session cookie (whilst_session) is set automatically. Public endpoints (no auth required):

GET /api/health
POST /api/auth/*
GET /api/oauth/*

Rate Limiting

MCP Server API keys: 100 requests/minute
Session-based: no explicit limit (protected by WorkOS session management)

OpenAPI Specification

The full OpenAPI 3.1 spec is available at openapi/openapi.yaml in the repository.