schemas/API_INVENTORY.md

# API response inventory (DTO sources)

Data originates from Supabase via `engine_*` modules and is exposed as JSON through FastAPI (`server.py`). The browser calls `/api/*` (Next.js rewrite to FastAPI).

## POST list item (feed, userPosts, station posts)

Typical keys after engine normalization:

| Field | Type (JSON) | Notes |
|-------|----------------|-------|
| id | string | |
| username | string | Author or station pseudo-user |
| content | string | |
| media_path | string | URL or path |
| timestamp | string | Unix or parsed string |
| comments_count | string | Coerced in engine |
| likes_count | string | |
| station_name | string | Empty for personal posts |
| avatar | string | User or station profile pic |
| is_liked | boolean | When viewer set |

## GET `/api/post/{post_id}`

Success: `{ "status": "success", "post": { ... } }` — post includes `select("*")` columns as strings plus `is_liked`, `avatar`.

Restricted: HTTP 403 `{ "status": "restricted", "username": ... }`.

## POST `/api/post/feed` and GET `/api/post/feed`

Success: `{ "status": "success", "feed": Post[], "posts": Post[] }` (same array twice for client compatibility).

## POST `/api/post/userPosts`

Success: `{ "status": "success", "posts": Post[] }` — optional `{ "blocked": true }` when viewer blocked.

## POST `/api/station/get`

Success: `{ "status": "success", "station": { station_name, admin, user_count, bio, hero_banner, profile_pic, users, members_info } | null }`.

## GET `/api/user/{username}/full`

Success: `{ "user": {...}, "avatar": str, "heroBanner": str }` — errors use `{ "error": str }`.

## Optional pagination (feed)

`FeedRequest` accepts optional `limit` (max 500) and `offset` for slicing the in-memory feed list after `get_feed` (does not change DB query yet).