API Overview

Route inventory, shared conventions, and baseline response contracts.

Base path and format

  • Base path: /api
  • Request and response: JSON unless explicitly noted
  • Authenticated routes require a valid NextAuth session

Route inventory

MethodRoutePurpose
*/api/auth/[...nextauth]Google OAuth login/logout/session
POST/api/groupsCreate a group and owner membership
GET/api/groupsList groups for current user
GET/api/groups/[id]Group detail with members + subscription
POST/api/groups/joinJoin by invite code
GET/api/subscriptions/catalogList active catalog services
GET/api/subscriptions/catalog/[id]Service detail + split preview
POST/api/groups/[id]/subscriptionAssign service to group
POST/api/billing/checkoutCreate Stripe Checkout session
GET/api/billing/paymentsPayment history for current user
POST/api/webhooks/stripeStripe event ingestion
GET/api/users/meProfile + dashboard summary

Authentication model

Most routes are protected and depend on session.user.id. Unauthenticated requests should return 401 with standardized error shape.

Error contract

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body failed validation.",
    "statusCode": 400
  }
}

Shared error classes

CodeTypical statusMeaning
UNAUTHORIZED401Missing or invalid auth session
FORBIDDEN403Authenticated but lacks permission
NOT_FOUND404Resource does not exist
VALIDATION_ERROR400Request contract invalid
CONFLICT409Duplicate state, existing relation, etc.
INTERNAL_ERROR500Unexpected unhandled error