Meet Transcriber — Status API Reference

Overview

The status website provides a human dashboard and machine-readable API for monitoring the Meet Transcriber bot in real time.

Surface	URL
Human dashboard	https://recorder.nicnames.dev
API base	https://api.recorder.nicnames.dev

---

Endpoints

GET /health

Liveness check.

Response:

{ "status": "ok" }

---

GET /api/events?show=new|all&limit=N

Returns events. Default show=new — only unread/new events from last 60 min.
Does NOT auto-mark as read. Use POST /api/events/read to acknowledge.

Query params: - show — new (default) or all - limit — max events to return (default: 100 for new, 20 for all)

Response:

{
  "events": [ <Event>, ... ],
  "count": 3,
  "hasErrors": false,
  "show": "new"
}

hasErrors is true if any returned event has type === "error".
show=new includes both status: "new" and status: "processing" events.

---

GET /api/events/all

Returns the last 20 events regardless of read state.
Designed for the human dashboard — always shows current state.

Response:

{
  "events": [ <Event>, ... ]
}

Events are returned newest-first.

---

---

POST /api/events/read

Explicitly mark events as read by ID. Non-destructive GET — reading events does not auto-mark them.

Body:

{ "ids": ["uuid1", "uuid2"] }

Response:

{ "marked": 2, "requested": 2 }

Events with status: "read" are excluded from GET /api/events?show=new.

---

POST /api/events/processing

Claim events as "in progress" by an agent. Sets status: "processing" on matching new events.
Processing events remain visible in show=new (for transparency) but signal other agents they're being handled.

Body:

{ "ids": ["uuid1"] }

Response:

{ "marked": 1, "requested": 1 }

Typical agent flow: 1. GET /api/events — fetch new events 2. POST /api/events/processing — claim the ones you're working on 3. Do the work 4. POST /api/events/read — mark complete

---

GET /screenshot?path=<encoded>

Serves a screenshot image file.

Query params: - path — URL-encoded absolute file path (must be under /tmp or /root/meet-transcriber)

Security: Paths outside the allowed prefixes return 403. Directory traversal attempts return 403.

Response: Image file (image/png, image/jpeg, etc.) or JSON error.

---

Event Object

{
  "id": "49f9c125-4a3c-4e88-a31c-d2e82641e91d",
  "ts": 1774564203888,
  "type": "screenshot",
  "text": "📍 Meet landing page (authenticated)\nURL: https://meet.google.com/landing",
  "mediaUrl": "/root/meet-transcriber/data/screenshots/sc_1774564201555_landing_poll.png",
  "read": false,
  "status": "new"
}

Field	Type	Description
id	string	UUID v4
ts	number	Unix timestamp in milliseconds
type	string	See Event Types below
text	string	Human-readable message text
mediaUrl	string|null	Absolute path to screenshot file, or null
read	boolean	true when status === "read"
status	string	"new", "processing", or "read"

Event Types

Type	Trigger
status	sendStatusUpdate() — general bot status messages
error	sendErrorNotification() — meeting or bot errors
meeting_found	sendMeetingFound() — new meeting detected
joined	sendJoinedNotification() — bot successfully joined a meeting
transcript	sendTranscriptNotification() — transcription delivered
screenshot	sendScreenshot() — debug/auth screenshots

---

Event Log Storage

Events are stored in /root/meet-transcriber/data/events.jsonl (newline-delimited JSON).

• Max size: 5 MB (auto-trimmed to last 2000 lines)
• Written synchronously from notifier.js on every outgoing Telegram message
• The status server reads/writes this file for all API responses
• Screenshots copied to /root/meet-transcriber/data/screenshots/ (persistent, last 50 kept) before /tmp cleanup

---

Agent Polling (Cron)

For automated error monitoring, poll /api/events every 10 minutes: - Events are marked as read on retrieval — no duplicates across polls - Check hasErrors field to detect issues requiring action - mediaUrl can be used to fetch screenshots for visual inspection via /screenshot

---

Infrastructure

Component	Details
Server	Node.js / Express, port 3456, 127.0.0.1 only
PM2 process	meet-status
Project path	/root/meet-transcriber-status/
Nginx	/etc/nginx/sites-available/recorder.nicnames.dev
SSL	Let's Encrypt, auto-renews