Utility APIs

ryOS provides several utility API endpoints for common operations like fetching link previews, checking iframe embeddability, sharing applets, cloud backup metadata, and admin operations. These endpoints are implemented as Node.js API functions.

Many utility endpoints now use the shared apiHandler + request-auth utilities for consistent CORS/auth/method handling.

Link Preview

Fetches metadata from URLs for rich link previews. Supports Open Graph, Twitter Cards, and standard meta tags with special handling for YouTube URLs.

Endpoint

Method	Path	Description
GET	`/api/link-preview`	Fetch URL metadata for previews

Request

Query Parameters:

Parameter	Type	Required	Description
`url`	string	Yes	The URL to fetch metadata from (must be HTTP or HTTPS)

Response

Success Response (200):

{
  "url": "https://example.com/page",
  "title": "Page Title",
  "description": "Page description from meta tags",
  "image": "https://example.com/og-image.jpg",
  "siteName": "Example Site"
}

Response Fields:

Field	Type	Description
`url`	string	The original URL
`title`	string?	Page title (from `<title>`, og:title, or twitter:title)
`description`	string?	Page description (from og:description, twitter:description, or meta description)
`image`	string?	Preview image URL (from og:image or twitter:image)
`siteName`	string?	Site name (from og:site_name or hostname)

Error Responses:

Status	Description
400	Missing or invalid URL
403	Unauthorized origin
405	Method not allowed
408	Request timeout
429	Rate limit exceeded
503	Network error

Rate Limits

Global limit: 10 requests per minute per IP

Per-host limit: 5 requests per minute per IP per target hostname

Example

// Fetch link preview
const response = await fetch('/api/link-preview?url=https://github.com');
const metadata = await response.json();

console.log(metadata);
// {
//   url: "https://github.com",
//   title: "GitHub: Let's build from here",
//   description: "GitHub is where over 100 million developers...",
//   image: "https://github.githubassets.com/images/modules/site/social-cards/campaign-social.png",
//   siteName: "GitHub"
// }

Notes

YouTube URLs are handled specially using the oEmbed API for reliable metadata

Responses are cached for 1 hour (Cache-Control: public, max-age=3600)
HTML entities in metadata are automatically decoded
Relative image URLs are converted to absolute URLs

iFrame Check

Checks if a URL allows iframe embedding and optionally proxies content to bypass embedding restrictions. Also supports retrieving cached historical versions of pages.

Endpoint

Method	Path	Description
GET	`/api/iframe-check`	Check iframe embeddability or proxy content

Request

Query Parameters:

Parameter	Type	Required	Description
`url`	string	Yes	The URL to check or proxy
`mode`	string	No	Operation mode: `check`, `proxy`, `ai`, or `list-cache` (default: `proxy`)
`year`	string	No	Year for Wayback Machine or AI cache (e.g., "2020", "1000 BC")
`month`	string	No	Month for Wayback Machine (e.g., "01" for January)
`theme`	string	No	Theme name - font overrides are skipped for "macosx" theme

Modes

`check` Mode

Performs a header-only check to determine if the URL allows iframe embedding.

Response (200):

{
  "allowed": true,
  "reason": null,
  "title": "Page Title"
}

{
  "allowed": false,
  "reason": "X-Frame-Options: DENY",
  "title": "Page Title"
}

`proxy` Mode (Default)

Proxies the content with embedding-blocking headers removed. Injects:

<base> tag for relative URL resolution
Click interceptor script for navigation handling
History API patch for cross-origin compatibility
Font override styles (unless theme is "macosx")

Response: The proxied HTML content with modified headers. Custom Response Headers:

Header	Description
`X-Proxied-Page-Title`	URL-encoded page title (if available)
`X-Wayback-Cache`	"HIT" if content was served from Wayback cache

`ai` Mode

Retrieves AI-generated historical page versions from cache.

Additional Parameters:

Parameter	Type	Required	Description
`year`	string	Yes	Historical year (e.g., "1995", "500 BC", "1 CE", "current")

Response (200) - Cache Hit:

Returns the cached HTML content with header X-AI-Cache: HIT.

Response (404) - Cache Miss:

{
  "aiCache": false
}

`list-cache` Mode

Lists all available cached years (both AI-generated and Wayback Machine) for a URL.

Response (200):

{
  "years": ["current", "2020", "2015", "2010", "1999", "500 BC"]
}

Auto-Proxy Domains

The following domains are automatically proxied regardless of mode:

wikipedia.org (and subdomains)
wikimedia.org (and subdomains)
wikipedia.com
cursor.com

Rate Limits

Mode	Global Limit	Per-Host Limit
`check` / `proxy`	300/min per IP	100/min per IP per host
`ai` / `list-cache`	120/min per IP	N/A

Example

// Check if URL can be embedded
const checkResponse = await fetch('/api/iframe-check?url=https://example.com&mode=check');
const { allowed, reason } = await checkResponse.json();

if (!allowed) {
  // Use proxy mode instead
  const iframeSrc = `/api/iframe-check?url=https://example.com&mode=proxy`;
  iframe.src = iframeSrc;
}

// List cached historical versions
const cacheResponse = await fetch('/api/iframe-check?url=https://example.com&mode=list-cache');
const { years } = await cacheResponse.json();
// years: ["2020", "2015", "2010"]

// Load Wayback Machine version
const waybackSrc = `/api/iframe-check?url=https://example.com&mode=proxy&year=2015&month=06`;

Share Applet

Manages sharing of user-created applets (mini HTML/JS applications). Supports creating, retrieving, updating, and deleting shared applets.

Endpoint

Method	Path	Description
GET	`/api/share-applet`	Retrieve applet by ID or list all applets
POST	`/api/share-applet`	Save or update an applet
DELETE	`/api/share-applet`	Delete an applet (admin only)
PATCH	`/api/share-applet`	Update applet metadata (admin only)

Authentication

Most operations require authentication via headers:

Header	Description
`Authorization`	Bearer token: `Bearer <token>`
`X-Username`	Username of the authenticated user

GET - Retrieve Applet

Query Parameters:

Parameter	Type	Required	Description
`id`	string	No	Applet ID to retrieve
`list`	string	No	Set to `"true"` to list all applets

*One of id or list=true is required.

Response - Single Applet (200):

{
  "content": "<html>...</html>",
  "title": "My Applet",
  "name": "my-applet",
  "icon": "game",
  "windowWidth": 400,
  "windowHeight": 300,
  "createdAt": 1704067200000,
  "createdBy": "username",
  "featured": false
}

Response - List Applets (200):

{
  "applets": [
    {
      "id": "abc123...",
      "title": "Featured Applet",
      "name": "featured-applet",
      "icon": "star",
      "createdAt": 1704067200000,
      "featured": true,
      "createdBy": "ryo"
    },
    {
      "id": "def456...",
      "title": "My Applet",
      "name": "my-applet",
      "icon": "game",
      "createdAt": 1704000000000,
      "featured": false,
      "createdBy": "user123"
    }
  ]
}

POST - Save Applet

Requires authentication.

Request Body:

Field	Type	Required	Description
`content`	string	Yes	HTML content of the applet
`title`	string	No	Display title
`name`	string	No	Applet name/slug
`icon`	string	No	Emoji or icon
`windowWidth`	number	No	Default window width
`windowHeight`	number	No	Default window height
`shareId`	string	No	Existing ID to update (author must match)

Response (200):

{
  "id": "abc123def456...",
  "shareUrl": "https://os.ryo.lu/applet-viewer/abc123def456...",
  "updated": false,
  "createdAt": 1704067200000
}

Response Fields:

Field	Type	Description
`id`	string	Unique applet ID (32 characters)
`shareUrl`	string	Full URL to view the applet
`updated`	boolean	Whether an existing applet was updated
`createdAt`	number	Timestamp of creation/update

DELETE - Delete Applet (Admin Only)

Requires admin authentication (user "ryo" with valid token).

Query Parameters:

Parameter	Type	Required	Description
`id`	string	Yes	Applet ID to delete

Response (200):

{
  "success": true
}

PATCH - Update Applet (Admin Only)

Currently only supports updating the featured status.

Query Parameters:

Parameter	Type	Required	Description
`id`	string	Yes	Applet ID to update

Request Body:

{
  "featured": true
}

Response (200):

{
  "success": true,
  "featured": true
}

Example

// Save a new applet
const response = await fetch('/api/share-applet', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
    'X-Username': username
  },
  body: JSON.stringify({
    content: '<html><body><h1>Hello World</h1></body></html>',
    title: 'Hello World Applet',
    icon: '👋',
    windowWidth: 400,
    windowHeight: 300
  })
});

const { id, shareUrl } = await response.json();
console.log(`Applet shared at: ${shareUrl}`);

// Retrieve an applet
const applet = await fetch(`/api/share-applet?id=${id}`).then(r => r.json());

// List all applets
const { applets } = await fetch('/api/share-applet?list=true').then(r => r.json());

Stocks API

Provides real-time stock quote data for the Dashboard Stocks widget. Uses Yahoo Finance for quote and chart data.

Endpoint

Method	Path	Description
GET	`/api/stocks`	Fetch stock quotes and optional chart data

Request

Query Parameters:

Parameter	Type	Required	Description
`symbols`	string	Yes	Comma-separated stock symbols (max 20)
`chart`	string	No	Symbol to fetch chart data for
`range`	string	No	Chart time range: `1d`, `5d`, `1mo`, `3mo`, `6mo` (default), `1y`, `2y`

Response

Success (200):

{
  "quotes": [
    {
      "symbol": "AAPL",
      "price": 198.50,
      "change": 2.30,
      "changePercent": 1.17,
      "name": "Apple Inc."
    }
  ],
  "chart": [
    {
      "timestamp": 1704067200000,
      "close": 195.20
    }
  ]
}

Response Fields:

Field	Type	Description
`quotes`	StockQuote[]	Array of stock quotes
`chart`	ChartPoint[]	Optional chart data (only when `chart` param provided)

Error Responses:

Status	Description
400	Missing `symbols` parameter or no valid symbols
500	Failed to fetch stock data

Caching

Responses include Cache-Control: public, max-age=60, stale-while-revalidate=300.

Example

const response = await fetch('/api/stocks?symbols=AAPL,GOOGL,MSFT&chart=AAPL&range=1mo');
const { quotes, chart } = await response.json();

Sync APIs (Cloud Backup Metadata)

The sync endpoints manage full backup metadata and logical domain sync around client-side object storage uploads.

Endpoint Summary

Method	Path	Description	Auth
POST	`/api/sync/backup-token`	Generate backup upload instructions	Required
GET	`/api/sync/status`	Check whether cloud backup metadata exists	Required
POST	`/api/sync/backup`	Save backup metadata after upload	Required
GET	`/api/sync/backup`	Download backup payload (base64) + metadata	Required
DELETE	`/api/sync/backup`	Delete backup blob + metadata	Required
GET	`/api/sync/domains`	Read logical and physical cloud sync metadata	Required
GET	`/api/sync/domains/[domain]`	Download a logical cloud sync domain payload	Required
PUT	`/api/sync/domains/[domain]`	Apply writes for one logical cloud sync domain	Required
POST	`/api/sync/domains/[domain]/attachments/prepare`	Generate upload instructions for blob-backed sync parts	Required

POST /api/sync/backup-token

Generates direct-upload instructions for backups/{username}/backup.gz. The route is rate-limited to 10 requests per hour per user.

Response:

{
  "provider": "vercel-blob",
  "uploadMethod": "vercel-client-token",
  "pathname": "backups/alice/backup.gz",
  "contentType": "application/gzip",
  "maximumSizeInBytes": 52428800,
  "clientToken": "vercel_blob_client_token..."
}

GET /api/sync/status

Returns hasBackup: false with metadata: null when no backup exists.

Response:

{
  "hasBackup": true,
  "metadata": {
    "timestamp": "2026-02-29T12:34:56.000Z",
    "version": 3,
    "totalSize": 1234567,
    "createdAt": "2026-02-29T12:35:10.000Z"
  }
}

/api/sync/backup

POST request body

{
  "storageUrl": "https://...blob.vercel-storage.com/backups/user/backup.gz",
  "timestamp": "2026-02-29T12:34:56.000Z",
  "version": 3,
  "totalSize": 1234567
}

blobUrl is also accepted for backward compatibility; the server resolves either field.

POST response

{
  "ok": true,
  "metadata": {
    "timestamp": "2026-02-29T12:34:56.000Z",
    "version": 3,
    "totalSize": 1234567,
    "createdAt": "2026-02-29T12:35:10.000Z"
  }
}

GET response

{
  "ok": true,
  "data": "BASE64_GZIP_DATA",
  "metadata": {
    "timestamp": "2026-02-29T12:34:56.000Z",
    "version": 3,
    "totalSize": 1234567,
    "createdAt": "2026-02-29T12:35:10.000Z"
  }
}

DELETE response

{
  "ok": true
}

GET /api/sync/domains

Returns two metadata maps for the authenticated user:

metadata: logical domains such as settings, files, and contacts

physicalMetadata: physical sync parts such as settings, custom-wallpapers, and files-images

GET /api/sync/domains/[domain]

Downloads a logical sync domain. The response includes aggregated logical metadata plus a parts object keyed by physical domain so Redis-backed and blob-backed data travel together.

PUT /api/sync/domains/[domain]

Applies grouped writes for a single logical sync domain. The request body contains a writes object keyed by physical domain, and clients may include X-Sync-Session-Id to help suppress self-triggered realtime updates.

POST /api/sync/domains/[domain]/attachments/prepare

Generates upload instructions for blob-backed logical sync parts. The request body includes a required partDomain and an optional itemKey for per-item blob domains such as custom-wallpapers or files-images.

Admin API

Administrative endpoints for user and memory management in the chat system. All operations require admin authentication (user ryo with valid token).

The endpoint is rate-limited to 30 admin requests/minute.

Endpoint

Method	Path	Description
GET	`/api/admin`	Query users and statistics
POST	`/api/admin`	Perform admin actions

Authentication

All admin endpoints require:

Header	Description
`Authorization`	Bearer token: `Bearer <token>`
`X-Username`	Must be `"ryo"`

Unauthorized requests return 403 Forbidden.

GET Operations

Query Parameters:

Parameter	Type	Required	Description
`action`	string	Yes	Operation to perform
`username`	string	For some actions	Target username
`limit`	number	No	Result limit (default: 50)

`getStats` Action

Get system-wide statistics.

Response:

{
  "totalUsers": 150,
  "totalRooms": 12,
  "totalMessages": 5430
}

`getAllUsers` Action

List all registered users.

Response:

{
  "users": [
    {
      "username": "alice",
      "lastActive": 1704067200000,
      "banned": false
    },
    {
      "username": "bob",
      "lastActive": 1704000000000,
      "banned": true
    }
  ]
}

`getUserProfile` Action

Get detailed profile for a specific user.

Additional Parameters:

Parameter	Type	Required	Description
`username`	string	Yes	Target username

Response:

{
  "username": "alice",
  "lastActive": 1704067200000,
  "banned": false,
  "banReason": null,
  "bannedAt": null,
  "messageCount": 42,
  "rooms": [
    { "id": "general", "name": "General Chat" },
    { "id": "random", "name": "Random" }
  ]
}

`getUserMessages` Action

Get recent messages from a specific user.

Additional Parameters:

Parameter	Type	Required	Description
`username`	string	Yes	Target username
`limit`	number	No	Maximum messages to return (default: 50)

Response:

{
  "messages": [
    {
      "id": "msg123",
      "roomId": "general",
      "roomName": "General Chat",
      "content": "Hello everyone!",
      "timestamp": 1704067200000
    }
  ]
}

`getUserMemories` Action

Get long-term memories plus recent daily notes for a user.

Additional Parameters:

Parameter	Type	Required	Description
`username`	string	Yes	Target username

Response:

{
  "memories": [
    {
      "key": "work",
      "summary": "Design lead at Cursor",
      "content": "...",
      "createdAt": 1704067200000,
      "updatedAt": 1704153600000
    }
  ],
  "dailyNotes": [
    {
      "date": "2026-02-29",
      "entries": [{ "timestamp": 1704067200000, "content": "..." }],
      "processedForMemories": false
    }
  ]
}

POST Operations

Request Body:

Field	Type	Required	Description
`action`	string	Yes	Operation to perform
`targetUsername`	string	Yes	User to act on
`reason`	string	No	Reason for action (for bans)

`deleteUser` Action

Permanently delete a user account (cannot delete admin "ryo").

Request:

{
  "action": "deleteUser",
  "targetUsername": "spammer"
}

Response:

{
  "success": true
}

Effects:

Deletes user record
Deletes password hash
Invalidates all authentication tokens

`banUser` Action

Ban a user from the chat system (cannot ban admin "ryo").

Request:

{
  "action": "banUser",
  "targetUsername": "troublemaker",
  "reason": "Spamming in chat"
}

Response:

{
  "success": true
}

Effects:

Sets banned: true on user record
Stores ban reason and timestamp
Invalidates all authentication tokens (forces logout)

`unbanUser` Action

Remove ban from a user.

Request:

{
  "action": "unbanUser",
  "targetUsername": "reformed-user"
}

Response:

{
  "success": true
}

`clearUserMemories` Action

Delete all long-term memories for a user.

{
  "action": "clearUserMemories",
  "targetUsername": "alice"
}

Response:

{
  "success": true,
  "deletedCount": 12,
  "message": "Cleared 12 memories for alice"
}

`forceProcessDailyNotes` Action

Reset processed flags and force reprocessing of recent daily notes into long-term memories.

{
  "action": "forceProcessDailyNotes",
  "targetUsername": "alice"
}

Response:

{
  "success": true,
  "notesReset": 7,
  "notesProcessed": 6,
  "memoriesCreated": 2,
  "memoriesUpdated": 1,
  "dates": ["2026-02-23", "2026-02-24"],
  "skippedDates": []
}

Example

const adminHeaders = {
  'Authorization': `Bearer ${adminToken}`,
  'X-Username': 'ryo'
};

// Get system statistics
const stats = await fetch('/api/admin?action=getStats', {
  headers: adminHeaders
}).then(r => r.json());

// Get all users
const { users } = await fetch('/api/admin?action=getAllUsers', {
  headers: adminHeaders
}).then(r => r.json());

// Get user profile
const profile = await fetch('/api/admin?action=getUserProfile&username=alice', {
  headers: adminHeaders
}).then(r => r.json());

// Ban a user
await fetch('/api/admin', {
  method: 'POST',
  headers: {
    ...adminHeaders,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'banUser',
    targetUsername: 'spammer',
    reason: 'Repeated spam violations'
  })
});

Telegram Link API

Manages linking ryOS accounts to Telegram for cross-platform notifications and chat integration. All endpoints require authentication.

Endpoint Summary

Method	Path	Description	Auth
POST	`/api/telegram/link/create`	Create a Telegram link code	Required
GET	`/api/telegram/link/status`	Check link status	Required
POST	`/api/telegram/link/disconnect`	Disconnect Telegram account	Required

POST /api/telegram/link/create

Generates a link code for connecting a Telegram account. If a pending link already exists, returns the existing code.

Response (200):

{
  "code": "abc123",
  "expiresIn": 300,
  "botUsername": "ryos_bot",
  "deepLink": "https://t.me/ryos_bot?start=link_abc123",
  "linkedAccount": null
}

If already linked:

{
  "code": null,
  "linkedAccount": {
    "telegramId": 123456789,
    "firstName": "Alice"
  }
}

GET /api/telegram/link/status

Check whether the authenticated user has a linked Telegram account or a pending link session.

Response (200):

{
  "linked": true,
  "account": {
    "telegramId": 123456789,
    "firstName": "Alice"
  },
  "pending": null
}

POST /api/telegram/link/disconnect

Disconnect a linked Telegram account.

Response (200):

{
  "success": true
}

Error Handling

All utility APIs return consistent error responses:

{
  "error": "Error message description"
}

Common HTTP Status Codes:

Status	Description
400	Bad request (missing/invalid parameters)
401	Unauthorized (authentication required)
403	Forbidden (insufficient permissions or blocked origin)
404	Not found
405	Method not allowed
408	Request timeout
429	Rate limit exceeded
500	Internal server error
503	Service unavailable

CORS

All utility APIs implement CORS with origin validation. Allowed origins are configured server-side. Requests from unauthorized origins receive 403 Forbidden.

API Reference - General API architecture

Rooms API - Chat room management
Messages API - Chat messaging
AI System - AI-powered features

Utility APIs

Link Preview

Endpoint

Request

Response

Rate Limits

Example

Notes

iFrame Check

Endpoint

Request

Modes

check Mode

proxy Mode (Default)

ai Mode

list-cache Mode

Auto-Proxy Domains

Rate Limits

Example

Share Applet

Endpoint

Authentication

GET - Retrieve Applet

POST - Save Applet

DELETE - Delete Applet (Admin Only)

PATCH - Update Applet (Admin Only)

Example

Stocks API

Endpoint

Request

Response

Caching

Example

Sync APIs (Cloud Backup Metadata)

Endpoint Summary

POST /api/sync/backup-token

GET /api/sync/status

/api/sync/backup

POST request body

POST response

GET response

DELETE response

GET /api/sync/domains

GET /api/sync/domains/[domain]

PUT /api/sync/domains/[domain]

POST /api/sync/domains/[domain]/attachments/prepare

Admin API

Endpoint

Authentication

GET Operations

getStats Action

getAllUsers Action

getUserProfile Action

getUserMessages Action

getUserMemories Action

POST Operations

deleteUser Action

banUser Action

unbanUser Action

clearUserMemories Action

forceProcessDailyNotes Action

Example

Telegram Link API

Endpoint Summary

POST /api/telegram/link/create

GET /api/telegram/link/status

POST /api/telegram/link/disconnect

Error Handling

CORS

Related

`check` Mode

`proxy` Mode (Default)

`ai` Mode

`list-cache` Mode

`getStats` Action

`getAllUsers` Action

`getUserProfile` Action

`getUserMessages` Action

`getUserMemories` Action

`deleteUser` Action

`banUser` Action

`unbanUser` Action

`clearUserMemories` Action

`forceProcessDailyNotes` Action