API Reference

API Overview

The platform provides a REST API at /api/v1/ for programmatic access. All routes use Supabase Auth for authentication — requests include the session cookie or a Bearer token.

Base URL

/api/v1/

Authentication

API requests use the Supabase session. When using the web app, the session cookie is sent automatically. For programmatic access, include the access token:

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

// Sign in with magic link
const { data, error } = await supabase.auth.signInWithOtp({
  email: "user@example.com",
});

// Use access token in requests
const token = data.session?.access_token;

Using the Token

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://yourplatform.com/api/v1/users/me

Endpoint Factories

Internally, routes use one of two patterns:

endpoint() — General-purpose handler with auth, permissions, and workspace isolation
creatorConsoleEndpoint() — For creator console routes; resolves active creator from staff membership
Mentorship routes — Custom auth via mentorship-auth.ts for cross-entity context (mentor, mentee, admin)

Response Format

Success Response

{
  "data": {},
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": {}
  }
}

API Endpoints

Users

GET    /api/v1/users/me                    # Current user
PUT    /api/v1/users/me                    # Update current user
GET    /api/v1/users/:id                   # Get user by ID
GET    /api/v1/users/me/preferences         # Get preferences
PUT    /api/v1/users/me/preferences         # Update preferences
GET    /api/v1/users/me/calendars           # List calendars
GET    /api/v1/users/me/calendars/:id       # Get calendar
PUT    /api/v1/users/me/calendars/connect   # Connect calendar
GET    /api/v1/users/me/calendars/callback   # OAuth callback
PUT    /api/v1/users/me/avatar              # Update avatar

Workspace

GET    /api/v1/workspace/settings           # Workspace settings
PUT    /api/v1/workspace/settings           # Update settings
GET    /api/v1/workspace/users              # Users in workspace
PUT    /api/v1/workspace/users/:userId/role # Update user role
PUT    /api/v1/workspace/logo               # Update workspace logo

Mentorship

GET    /api/v1/mentorship/mentors                    # List mentors
GET    /api/v1/mentorship/mentors/:id                # Mentor details
GET    /api/v1/mentorship/mentors/:id/programmes     # Mentor programmes
GET    /api/v1/mentorship/mentors/:id/programmes     # Programme mentors
GET    /api/v1/mentorship/sessions                   # List sessions
GET    /api/v1/mentorship/sessions/:id               # Session details
POST   /api/v1/mentorship/sessions/:id/cancel        # Cancel session
GET    /api/v1/mentorship/sessions/:id/notes        # Session notes
POST   /api/v1/mentorship/book                       # Book session
GET    /api/v1/mentorship/slots                      # Available slots
GET    /api/v1/mentorship/availability               # Mentor availability
GET    /api/v1/mentorship/pairings                   # List pairings
GET    /api/v1/mentorship/pairings/:id               # Pairing details
GET    /api/v1/mentorship/staff/credits              # Staff credits view
GET    /api/v1/mentorship/company-staff              # Company staff
GET    /api/v1/mentorship/mentees                    # Mentees
GET    /api/v1/mentorship/staff/companies             # Staff companies
GET    /api/v1/mentorship/programmes                 # Mentorship programmes

Creator Console

GET    /api/v1/creator/me                    # Current creator
GET    /api/v1/creator/me/resources          # Creator resources
GET    /api/v1/creator/me/resources/:id      # Resource details
POST   /api/v1/creator/me/resources          # Create resource
PUT    /api/v1/creator/me/resources/:id     # Update resource
GET    /api/v1/creator/me/staff              # Creator staff
GET    /api/v1/creator/me/staff/:staffId     # Staff member
GET    /api/v1/creator/me/analytics          # Creator analytics
GET    /api/v1/creator/me/stats              # Creator stats
GET    /api/v1/creators/:id                  # Creator by ID
GET    /api/v1/creators/:id/programmes       # Creator programmes
GET    /api/v1/creators/:id/staff            # Creator staff

UI/Feed

GET    /api/v1/ui/for-you                    # For You feed (personalised)
POST   /api/v1/ui/for-you/interaction        # Log impression/interaction
GET    /api/v1/ui/browse                      # Browse resources
GET    /api/v1/ui/browse/channel              # Channel feed

Resources & Tags

GET    /api/v1/resources/:id                 # Resource details
GET    /api/v1/tags                           # List tags

Auth & Attribution

POST   /api/v1/auth/claim-share-attribution   # Claim share attribution
POST   /api/v1/auth/claim-utm                 # Claim UTM params
POST   /api/v1/auth/link-demo-tenant          # Link demo tenant

AI

POST   /api/v1/classify                      # URL scraping + AI classification (type, tags, metadata)

OG & Metadata

GET    /api/v1/og-metadata                   # Open Graph metadata
GET    /api/v1/og-image                      # OG image generation

Client Data Fetching

For client-side use, the app uses TanStack Query hooks in hooks/queries/ that call these /api/v1/ endpoints. No direct Supabase calls from client components.

Next Steps

Database Schema — Data structures and relationships
Architecture — Endpoint factories, repository pattern, permissions

API Reference

On this page