API Reference

ryOS backend APIs use Node-style route handlers in api/, served by the standalone Bun API server.

Most actively refactored JSON routes use the shared apiHandler utility (api/_utils/api-handler.ts) for CORS, method checks, auth resolution, and consistent error handling. Some specialized routes (for example multipart upload handlers) still use explicit/manual handling.

API Request Flow

graph LR
    Client[Client App] --> Auth{Auth Check}
    Auth -->|Valid| Router[API Router]
    Auth -->|Invalid| Error[401 Error]
    Router --> API[Node.js Runtime]
    API --> Services[External Services]
    Services --> AI[AI Providers]
    Services --> DB[(Redis/KV)]
    Services --> Media[Media APIs]
    API --> Response[JSON Response]
    Response --> Client

Endpoint Documentation

Cross-Cutting Handler Pattern

• apiHandler: shared wrapper for CORS preflight, origin checks, method allowlists, optional JSON parsing, unified logger wiring, and default JSON error handling.

• request-auth: shared auth resolver for token endpoints, expecting:
  • Authorization: Bearer {token}
  • X-Username: {username}
• Partial auth headers return 400.
• Invalid token/username pairs return 401.
• Optional-auth endpoints can be anonymous while still validating provided auth headers.

Infrastructure Adapters

• Redis (api/_utils/redis.ts): Centralized Redis client factory supporting Upstash REST (REDIS_KV_REST_API_URL) and standard Redis (REDIS_URL) backends with a unified API.

• Storage (api/_utils/storage.ts): Switchable object storage adapter for Sync v2 blobs and media assets.

Quick Reference

AI Endpoints

Media Endpoints

Communication Endpoints

APNs pushes (api/_utils/push-relay.ts) fire when a room message is broadcast: private rooms notify the other members' devices; public/IRC rooms notify only devices that listed the room in rooms. Devices are dropped when their registering session signs out, on logout-all, and on account deletion. bun run push:test <token> [sandbox|prod] sends a test alert.

Push logs are prefixed [push] (device tokens shown as abcd…wxyz; no JWTs, keys, session tokens, or message text). Production logs one notifyRoomMessage done summary per message with outcome counts (sent, failed, dead, duplicate, sessionDead, ineligible, …) plus warnings for APNs failures, dead-token removal, and env changes. Set RYOS_DEBUG=1 (the shared API debug flag) to also log each skip reason, burst grouping, and every APNs attempt's env/status/reason.

The web client logs its half under the same [push] scope via createClientLogger (debug mode: dev builds or localStorage["ryos:debug"] = "1"): permission requests, shell configure/room-state sync, which display path a chat notification took (shell / browser / toast), and notification taps. The iOS shell logs ryOS: [push] … lines via NSLog (Console.app / Xcode): permission result, APNs token (redacted), api/push/register and AirBuild fallback status codes, local notifications, and tap → web delivery.

Utility Endpoints

Endpoint Categories Overview

graph TD
    API["/api/*"]
    API --> AI[AI Services]
    API --> Media[Media Services]
    API --> Comm[Communication]
    API --> Util[Utilities]
    
    AI --> chat["/chat"]
    AI --> applet["/applet-ai"]
    AI --> ie["/ie-generate"]
    AI --> parse["/parse-title"]
    
    Media --> song["/songs"]
    Media --> speech["/speech"]
    Media --> transcribe["/audio-transcribe"]
    Media --> yt["/youtube-search"]
    
    Comm --> rooms["/rooms"]
    Comm --> messages["/messages/bulk"]
    Comm --> presence["/presence/switch"]
    Comm --> users["/users"]
    Comm --> ryo["/ai/ryo-reply"]
    Comm --> listen["/listen/sessions"]
    Comm --> telegram["/telegram/link"]
    
    Util --> preview["/link-preview"]
    Util --> iframe["/iframe-check"]
    Util --> share["/share-applet"]
    Util --> stocks["/stocks"]
    Util --> sync["/sync/v2/*"]
    Util --> admin["/admin"]

Authentication

Browser sessions use an httpOnly ryos_auth cookie set by register, login, token/verify, token/refresh, and session. Programmatic clients may still use Bearer + X-Username headers:

Authorization: Bearer {token}
X-Username: {username}

Token-based sessions use a 1-year TTL, refreshed on each validated request. Auth-required endpoints use the shared request-auth validation boundary for consistent 400/401 semantics.

Standalone Bun Server Routes

When running via scripts/api-standalone-server.ts:

Environment Variables

AI Providers