From f82d0340be76f6736570f5a5223de3d6a4b74e69 Mon Sep 17 00:00:00 2001 From: st Date: Wed, 8 Jul 2026 13:37:36 -0500 Subject: [PATCH] Add REFERENCE.md --- REFERENCE.md | 337 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 REFERENCE.md diff --git a/REFERENCE.md b/REFERENCE.md new file mode 100644 index 0000000..e172446 --- /dev/null +++ b/REFERENCE.md @@ -0,0 +1,337 @@ +# TACHYON API Reference + +Base URL (local dev): `http://localhost:3000` +Base URL (once deployed behind the tunnel, e.g.): `https://api.radium.wtf` + +All request/response bodies are JSON. `POST`/`PUT` requests must send +`Content-Type: application/json`. + +--- + +## Health + +### `GET /api/health` + +Liveness check — confirms the API process is up and responding. + +**Response `200`** +```json +{ "ok": true } +``` + +**Example** +```bash +curl http://localhost:3000/api/health +``` + +--- + +## News + +Backed by the `news_posts` table. Powers the **News** panel. + +### `GET /api/news` + +List news posts, newest first. + +**Query params** + +| Param | Type | Default | Notes | +|---------|--------|---------|---------------------------------| +| `limit` | number | `20` | Capped at `100` | + +**Response `200`** +```json +[ + { + "id": 3, + "title": "Placeholder announcement title", + "content": "Short placeholder line describing an update or change.", + "created_at": "2026-07-06T12:00:00.000Z" + } +] +``` + +**Example** +```bash +curl "http://localhost:3000/api/news?limit=5" +``` + +--- + +### `POST /api/news` + +Create a news post. + +**Body** + +| Field | Type | Required | +|-----------|--------|----------| +| `title` | string | yes | +| `content` | string | yes | + +**Response `201`** — the created row (with generated `id` and `created_at`) +```json +{ + "id": 4, + "title": "New post title", + "content": "New post body text.", + "created_at": "2026-07-08T18:30:00.000Z" +} +``` + +**Response `400`** — missing fields +```json +{ "error": "title and content are required" } +``` + +**Example** +```bash +curl -X POST http://localhost:3000/api/news \ + -H "Content-Type: application/json" \ + -d '{"title": "New post title", "content": "New post body text."}' +``` + +--- + +### `DELETE /api/news/:id` + +Delete a news post by id. + +**Response `204`** — no body, success. +**Response `404`** +```json +{ "error": "not found" } +``` + +**Example** +```bash +curl -X DELETE http://localhost:3000/api/news/4 +``` + +--- + +## Media + +Backed by the `media_items` table. Powers the **Media** grid. + +### `GET /api/media` + +List media items, newest first. + +**Query params** + +| Param | Type | Default | Notes | +|---------|--------|---------|---------------------------------| +| `limit` | number | `24` | Capped at `100` | + +**Response `200`** +```json +[ + { + "id": 1, + "title": "placeholder clip one", + "media_type": "image", + "url": "https://example.com/media/1.png", + "created_at": "2026-07-08T17:59:31.129Z" + } +] +``` + +**Example** +```bash +curl "http://localhost:3000/api/media?limit=12" +``` + +--- + +### `POST /api/media` + +Add a media item. + +**Body** + +| Field | Type | Required | Notes | +|--------------|--------|----------|----------------------------------| +| `title` | string | yes | | +| `media_type` | string | yes | must be `"image"` or `"video"` | +| `url` | string | yes | | + +**Response `201`** — the created row +```json +{ + "id": 5, + "title": "new clip", + "media_type": "video", + "url": "https://example.com/media/5.mp4", + "created_at": "2026-07-08T18:35:00.000Z" +} +``` + +**Response `400`** +```json +{ "error": "title, url, and media_type (image|video) are required" } +``` + +**Example** +```bash +curl -X POST http://localhost:3000/api/media \ + -H "Content-Type: application/json" \ + -d '{"title": "new clip", "media_type": "video", "url": "https://example.com/media/5.mp4"}' +``` + +--- + +### `DELETE /api/media/:id` + +Delete a media item by id. + +**Response `204`** — no body, success. +**Response `404`** +```json +{ "error": "not found" } +``` + +**Example** +```bash +curl -X DELETE http://localhost:3000/api/media/5 +``` + +--- + +## Stats + +Backed by `users`, `sessions`, `activity_log`, and `site_stats`. Powers the +**Overview** panel (Current Users / Recent Activity / General Statistics +columns). + +### `GET /api/stats/overview` + +The main endpoint for this panel — returns all three columns in a single +call so the frontend doesn't need three round trips. + +**Response `200`** +```json +{ + "currentUsers": [ + { "id": 1, "username": "placeholder_user_01", "started_at": "2026-07-08T18:00:00.000Z" } + ], + "recentActivity": [ + { "id": 1, "description": "placeholder event one", "created_at": "2026-07-08T17:00:00.000Z" } + ], + "general": { + "users": { + "total": 3, + "mostRecent": { "username": "placeholder_user_03", "id": 3 } + }, + "reports": { "named": "00", "associated": "00", "logged": "00" }, + "build": { "pipeline": "Completed", "buildNumber": "00000000", "version": "0.0.0" } + } +} +``` + +- `currentUsers` — users with an open session (`sessions.ended_at IS NULL`), most recently started first. +- `recentActivity` — latest rows from `activity_log`. +- `general.users.total` — total row count in `users` (not just online users). +- `general.reports` / `general.build` — pulled from the `site_stats` key/value table; update these directly in the DB or add an admin endpoint if you want them editable via API. + +**Example** +```bash +curl http://localhost:3000/api/stats/overview +``` + +--- + +### `GET /api/stats/users` + +Just the current-users list, if you want it without the rest of the +overview payload (e.g. a lighter-weight poll for a live "online now" count). + +**Response `200`** +```json +[ + { "id": 1, "username": "placeholder_user_01", "started_at": "2026-07-08T18:00:00.000Z" } +] +``` + +**Example** +```bash +curl http://localhost:3000/api/stats/users +``` + +--- + +### `POST /api/stats/session/start` + +Marks a user as online by opening a session. Creates the user row if the +username doesn't exist yet. + +**Body** + +| Field | Type | Required | +|------------|--------|----------| +| `username` | string | yes | + +**Response `201`** +```json +{ "sessionId": 7, "userId": 3 } +``` + +**Response `400`** +```json +{ "error": "username is required" } +``` + +**Example** +```bash +curl -X POST http://localhost:3000/api/stats/session/start \ + -H "Content-Type: application/json" \ + -d '{"username": "placeholder_user_04"}' +``` + +> Save the returned `sessionId` — you'll need it to end the session later. + +--- + +### `POST /api/stats/session/end` + +Marks a session as ended (user no longer counted as "current"). + +**Body** + +| Field | Type | Required | +|-------------|--------|----------| +| `sessionId` | number | yes | + +**Response `204`** — no body, success. +**Response `400`** +```json +{ "error": "sessionId is required" } +``` +**Response `404`** — id doesn't exist or was already ended +```json +{ "error": "no active session with that id" } +``` + +**Example** +```bash +curl -X POST http://localhost:3000/api/stats/session/end \ + -H "Content-Type: application/json" \ + -d '{"sessionId": 7}' +``` + +--- + +## Error format + +All error responses follow the same shape: + +```json +{ "error": "human-readable message" } +``` + +There's no auth layer on any of this yet — every endpoint above is open. +Add something (API key header, session cookie, whatever fits your setup) +before exposing the write endpoints (`POST`/`DELETE`) publicly, since right +now anyone who can reach the API can create/delete news and media or spoof +"current users." \ No newline at end of file