337 lines
7.1 KiB
Markdown
337 lines
7.1 KiB
Markdown
# 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." |