Skip to content

API Reference

Jump to bottom
github-actions[bot] edited this page Aug 8, 2026 · 25 revisions

API Reference

All API routes live under /api/* and are handled by PHP.

Auth and Account

/api/account/is-admin

  • Returns { isAdmin: boolean }
  • Refreshes frontend admin awareness for maintenance-mode bypass logic

/api/settings

GET

  • Requires logged-in user
  • Returns current settings from data/accounts/accounts.json
  • Currently exposes theme, glowIntensity, colors, onekoEnabled, reduceMotion, titleAnimation, titleAnimationAlways, titleAnimationDesync, browserNotificationsEnabled, and journalBrowserNotificationsEnabled; colors is honored by classic for the full palette and by ambercrt/CRT for the single links phosphor color
  • Toast-only settings fields are documented on Toast

POST

  • Requires logged-in user
  • Updates user settings in accounts.json
  • Can set theme to default, classic, or a valid /themes/*.json theme id
  • Can set the reduced-motion accessibility boolean
  • Can set the validated title animation id plus the always-playing and character-desync booleans
  • Can set onekoEnabled for the optional cursor-following cat
  • Can set browserNotificationsEnabled for account-backed browser feed notification polling
  • Can set journalBrowserNotificationsEnabled for account-backed new journal post browser notifications
  • Syncs the theme_pref cookie so anonymous and first-load rendering can pick the active theme
  • Validates color fields as #RRGGBB; the settings UI sends the full palette for classic and only links for CRT
  • Admin users can also toggle maintenance mode through the settings flow
  • Toast-only personality persistence is documented on Toast

/api/dev-bootstrap

POST

  • Developer-mode-only route used by /settings
  • Allowed for admin sessions, or for local setups with no admin account yet
  • Streams newline-delimited JSON progress while it finds the latest sanitized Google Drive developer data zip, downloads it, extracts it, deletes existing local data/, and installs the new copy
  • Progress events may include a log field for the settings popup; download logs show byte counts/percentages, and extraction logs include entry counts/percentages
  • Bootstrap-stream diagnostics and their sanitization rules are documented on Debug Mode

/api/themes

GET

  • Public route
  • Returns selectable themes, with default displayed as blackprint before discovered themes
  • Each valid theme must include name, description, thumbnail, html, and css
  • Theme html and css paths are resolved from /themes/lib; picker thumbnails are resolved from /themes

/api/bookmark

POST only.

  • Requires logged-in user for server persistence
  • Supports single toggle via postId
  • Supports full replacement via bookmarks
  • Writes normalized bookmark ids back to accounts.json
  • Bookmark ids currently include raw feed ids and journal:{id}; legacy newsletter:{id} values may exist but are ignored
  • Anonymous bookmarking is handled client-side in localStorage instead

Content / Media

/tools/upload/?api=*

Route-local JSON endpoints for the /tools/upload peer-to-peer transfer page, displayed as serverless upload.

  • POST ?api=create with role=sender|receiver creates a short-lived room and returns /tools/upload/?r={token}
  • GET ?api=room&r={token} claims/loads a room for the creator browser or first guest browser
  • POST ?api=key&r={token} stores one peer's ephemeral ECDH public key
  • POST ?api=signal&r={token} stores WebRTC offer/answer/ICE signaling messages
  • GET ?api=signals&r={token}&since={id} polls signaling messages from the other peer
  • POST ?api=heartbeat&r={token} keeps the peer's side alive while the tab is open
  • POST ?api=end&r={token} ends the room when either peer closes the tab
  • Room access is locked by the HttpOnly fridg3_upload_peer browser cookie
  • Stores only room metadata/signaling in data/upload/rooms.json; file contents are sent peer-to-peer and are not written by PHP

/tools/mdpaste/

POST JSON payload with { markdown, password, hardBreaks }.

  • Stores temporary markdown paste records in data/mdpaste
  • Empty passwords create public pastes
  • Non-empty passwords encrypt the markdown before storage
  • hardBreaks stores whether single line breaks render as line breaks in formatted paragraphs
  • Returns { ok, id, url, expires_at, encrypted }
  • Rejects blank pastes and content over 512 KiB

/api/feed-post

  • Returns parsed feed post JSON for a supplied ?id=
  • Does not expose replies; thread replies are loaded directly by /feed/posts/{id} from data/feed/replies/*.json

/api/feed-notifications

GET, optionally with guestBrowserId={32 hex chars} for logged-out browsers.

  • Returns current browser notification candidates for feed and journal events
  • Account notification event parity with Discord is documented on Toast
  • Guest events cover replies to guest comments created by the same browser token
  • Journal events cover new published journal posts for both guests and logged-in users
  • Clients keep seen notification keys in localStorage, filter event type, and use this endpoint for browser Notification API polling

Toast Feed Generation

The Toast-only feed generation API is documented on Toast.

/api/gallery/delete

  • Admin-only image deletion from data/images
  • Validates filename/path and allowed image extensions

/api/sitemap

  • Admin-only sitemap generator
  • Scans routes and content files
  • Writes /sitemap.xml
  • Writes a two-line XML comment immediately after the declaration containing This sitemap was automatically generated. and the generation time in DD/MM/YY HH:MM:SS format

Toast APIs

Toast feed generation, status, stream control, playback proxy, and localhost service integrations are documented on Toast.

Telemetry / System

/api/page-view

POST JSON payload with { path }.

  • Normalizes route path
  • Rejects /api/* paths
  • Hashes client IP before storage
  • Updates data/etc/page_views.json
  • Returns updated page count

/api/system/usage

  • Returns CPU, memory, and disk usage data
  • Includes Linux and Windows code paths

Implementation Notes

  • Most endpoints return JSON and perform direct file IO
  • Write-heavy endpoints should be treated carefully because there is no database transaction safety blanket here
  • /api/page-view already uses file locking, which is the sane move
  • Toast's localhost-only endpoints and integrations are documented on Toast

Clone this wiki locally