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

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["/song/*"]
    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/* + backup"]
    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