# API Reference

The backend is a FastAPI application. In local development or deployed environments that keep FastAPI's default documentation enabled, interactive schemas are typically available at `/docs`, `/redoc`, and `/openapi.json`.

Most product endpoints expect a bearer token issued through Supabase after the Sejong sign-in bootstrap flow.

## Authentication and Onboarding

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/api/auth/sejong/session` | Validate Sejong credentials, bootstrap or look up the internal Supabase account, and return onboarding context |
| `POST` | `/api/auth/send-welcome` | Trigger welcome-email behavior |
| `GET` | `/api/meta/onboarding` | Return onboarding metadata |
| `GET` | `/api/profiles/pseudonym-availability` | Check whether a pseudonym can be used |
| `POST` | `/api/profiles/onboarding` | Create the initial student profile |

## Profiles, Discovery, and Social Graph

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/api/profiles/{user_id}` | Fetch the signed-in user's full profile |
| `PUT` | `/api/profiles/{user_id}` | Update the signed-in user's profile |
| `GET` | `/api/profiles/{user_id}/public` | Fetch the public profile view for another student |
| `GET` | `/api/users/search` | Search for users |
| `GET` | `/api/recommendations/{user_id}` | Fetch recommended users |
| `GET` | `/api/matches` | List matches |
| `POST` | `/api/matches` | Create a match request or record |
| `PATCH` | `/api/matches/{match_id}` | Update match state |
| `DELETE` | `/api/matches/{match_id}` | Remove a match |
| `GET` | `/api/presence` | List current presence information |
| `PUT` | `/api/presence/me` | Update the current user's presence |

## Pulse Feed and Content

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/api/pulses` | List feed items |
| `GET` | `/api/pulses/search` | Search indexed pulses |
| `GET` | `/api/pulses/{pulse_id}` | Fetch a single pulse |
| `POST` | `/api/pulses` | Create a pulse |
| `DELETE` | `/api/pulses/{pulse_id}` | Remove a pulse |
| `POST` | `/api/pulses/{pulse_id}/like` | Toggle or record a reaction |
| `GET` | `/api/pulses/{pulse_id}/comments` | List comments for a pulse |
| `POST` | `/api/pulses/{pulse_id}/comment` | Add a comment |
| `POST` | `/api/pulses/translate` | Translate pulse content |
| `POST` | `/api/feed-events` | Record feed analytics or interaction events |

## Chat, Advisor, Channels, and Calls

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/api/chat` | Submit a chat request |
| `POST` | `/api/chat/stream` | Receive streaming chat responses |
| `POST` | `/api/advisor/query` | Legacy advisor-compatible chat request |
| `POST` | `/api/chat/feedback` | Submit turn-level feedback |
| `POST` | `/api/chat/create-user` | Provision or bootstrap chat identity |
| `POST` | `/api/chat/notify-message` | Trigger message notifications |
| `POST` | `/api/chat/notify-call` | Trigger call notifications |
| `POST` | `/api/video/session` | Create a LiveKit session token and metadata |
| `GET` | `/api/channels` | List channels |
| `PUT` | `/api/channels/membership` | Join or update channel membership |
| `PUT` | `/api/channels/membership/role` | Change membership roles |
| `DELETE` | `/api/channels/membership/{channel_key}` | Leave or remove membership |
| `PUT` | `/api/channels/{channel_key}/pins` | Manage pinned content in a channel |

## Notifications, Settings, Privacy, and Moderation

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/api/notifications` | List notifications |
| `PATCH` | `/api/notifications/{notification_id}/read` | Mark one notification as read |
| `PATCH` | `/api/notifications/read-all` | Mark all notifications as read |
| `GET` | `/api/privacy/preferences` | Fetch privacy settings |
| `PUT` | `/api/privacy/preferences` | Update privacy settings |
| `GET` | `/api/settings/preferences` | Fetch app-level preferences |
| `PUT` | `/api/settings/preferences` | Update app-level preferences |
| `GET` | `/api/settings/sticker-packs` | List sticker packs |
| `POST` | `/api/settings/support-request` | Send a support request |
| `POST` | `/api/moderation/reports` | Submit a moderation report |
| `GET` | `/api/moderation/reports` | List moderation reports |
| `PATCH` | `/api/moderation/reports/{report_id}` | Update moderation state |

## Billing

Billing routes are mounted through `stitch/backend/controllers/billing_controller.py`.

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/api/billing/status` | Return plan, credits, and billing status |
| `POST` | `/api/billing/subscription/create` | Create a subscription checkout |
| `POST` | `/api/billing/subscription/activate` | Activate a subscription after checkout |
| `POST` | `/api/billing/subscription/cancel-renewal` | Cancel renewal for an active subscription |
| `POST` | `/api/billing/credit-packs/create-order` | Create a credit-pack order |
| `POST` | `/api/billing/credit-packs/capture-order` | Capture a completed credit-pack order |
| `POST` | `/api/billing/checkout/failure` | Record a failed checkout attempt |
| `POST` | `/api/billing/internal/renew-due` | Internal renewal processing job endpoint |
| `POST` | `/api/billing/paypal/webhook` | Billing provider webhook ingestion |

## Health and Diagnostics

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/` | Simple root response |
| `GET` | `/api/health` | API health and startup diagnostics |
| `GET` | `/api/recommendation/health` | Recommendation-system health snapshot |

## Notes

- Route coverage in this page is intentionally grouped for readability rather than generated directly from the OpenAPI schema.
- For exact request and response payloads, use the live FastAPI schema from the running backend.