# NG Share Platform — Full API Reference > ng.net is a next-gen website sharing platform built on Cloudflare Workers. > Anyone can anonymously submit URLs. AI auto-categorizes them. Users interact via real-time chat. Base URL: https://ng.net Authentication: Most endpoints are public. Some features require email login (cookie-based session). --- ## Data Models ### Site { "id": "string (nanoid)", "url": "string (full URL)", "title": "string", "description": "string", "favicon_url": "string (URL)", "og_image_url": "string (URL or empty)", "domain": "string (e.g. example.com)", "tags": ["string array — AI-generated categories"], "submit_count": "integer — how many times submitted", "click_count": "integer", "hot_score": "number — trending score, higher = more popular", "first_submitted_at": "ISO 8601 datetime", "last_activity_at": "ISO 8601 datetime", "site_type": "'website' | 'profile'", "social_platform": "string — platform name for profiles (twitter, instagram, github, etc.)", "social_username": "string — username for profiles", "boost_count": "integer", "is_claimed": "boolean — site owner has verified ownership", "is_promoted": "boolean — currently running a paid promotion", "promoted_until": "ISO 8601 datetime or empty" } ### ChatMessage { "id": "string", "type": "'chat' | 'system' | 'entrance'", "content": "string", "content_key": "string (optional — i18n key for system messages)", "content_params": "object (optional — interpolation params for i18n)", "sender_name": "string — display name or geo-based anonymous name (English)", "sender_location": "string (optional — e.g. 'CN|Beijing', 'US|Dallas')", "created_at": "ISO 8601 datetime" } ### Valid Tags 工具 (Tools), 技术 (Tech), 设计 (Design), 新闻 (News), 社区 (Community), 学习 (Learning), 娱乐 (Entertainment), 资源 (Resources), 商业 (Business), 生活 (Lifestyle), 社交 (Social) Note: Tags are stored as Chinese strings in the database. AI assigns 1-3 tags from this list by analyzing the page content with Meta Llama 3.1 8B Instruct. Tags are displayed in the user's language via i18n mapping on the client side. ### Supported Languages zh-CN (Simplified Chinese), zh-HK (Hong Kong Traditional), zh-TW (Taiwan Traditional), en (English), es (Spanish), ar (Arabic), hi (Hindi), pt (Portuguese), ja (Japanese), ko (Korean), fr (French), de (German) --- ## API Endpoints ### 1. GET /api/sites — Search Sites Query Parameters: - sort: "hot" (default) | "recent" - tag: string (optional) — filter by tag - search: string (optional) — keyword search - page: integer (default 1) — 60 items per page Response 200: { "sites": [Site, ...], "total": 123, "page": 1, "hasMore": true } ### 2. POST /api/sites — Submit URL Request Body: { "url": "https://example.com", // required "turnstileToken": "cf-turnstile-..." // required when CAPTCHA is enabled } Response 201 (new site): { "site": Site, "isNew": true } Response 200 (existing site, submit count incremented): { "site": Site, "isNew": false } Errors: - 400: Invalid URL or request format - 403: Missing or invalid Turnstile token - 429: Rate limited (max 5 per minute per IP) Notes: - Social profile URLs (Twitter, Instagram, GitHub, etc.) are auto-detected - AI generates tags asynchronously after submission - Metadata (title, description, favicon, OG image) is fetched server-side - Login wall detection: if a site requires login to view, screenshot fallback is disabled ### 3. GET /api/sites/tags — Get All Tags Response 200: { "tags": ["工具", "技术", "设计", ...] } ### 4. POST /api/sites/{id}/boost — Boost Site Path: id = site ID (nanoid string) Response 200: { "site": Site, "credits": 0 } Errors: - 404: Site not found - 429: Daily boost limit reached (1/day free, 3/day for logged-in users) ### 5. POST /api/sites/{id}/claim — Claim Site Ownership Requires: Add to your site's HTML . How it works: 1. Find your site on ng.net and note the site ID from the URL or card 2. Add the meta tag to your site's HTML section 3. Call this endpoint — our server will fetch your page and verify the tag Response 200: { "site": Site, "verified": true } Errors: - 400: Verification meta tag not found, or site already claimed - 404: Site not found Benefits of claiming: - Verified badge on your site card - Access to click analytics - Priority display in search results - Manage site description and tags ### 6. POST /api/clicks/{id} — Record Click Path: id = site ID Rate limit: 30/min per IP Response 200: { "recorded": true } ### 7. GET /api/messages — Get Chat Messages Query Parameters: - limit: integer (default 50, max 100) Response 200: { "messages": [ChatMessage, ...] } ### 8. POST /api/messages — Send Chat Message Request Body: { "content": "string (max 200 chars)" } Response 201: { "message": ChatMessage } Errors: - 400: Empty message or exceeds 200 characters - 429: Rate limited (10/min per IP) ### 9. POST /api/translate — Translate Text Request Body: { "text": "string (max 2000 chars)", "targetLang": "en" // one of the supported language codes } Response 200: { "translated": "translated text" } Errors: - 400: Missing params or text too long - 429: Rate limited (20/min per IP) - 500: AI translation failed Notes: - Uses Cloudflare Workers AI (M2M100-1.2B model) - Source language is auto-detected - Supported target languages: zh-CN, zh-HK, zh-TW, en, es, ar, hi, pt, ja, ko, fr, de ### 10. GET /api/bing-bg — Daily Background Image Response 200: { "imageUrl": "https://www.bing.com/...", "videoUrl": "https://..." or null, "copyright": "Photo credit...", "title": "Image title" } Notes: Cached for 6 hours. Proxies Bing's daily image API. ### 11. GET /api/ws — WebSocket (Real-time Chat) Upgrade: websocket Connects to the live chat room powered by Cloudflare Durable Objects. No authentication required. #### Connection const ws = new WebSocket("wss://ng.net/api/ws"); #### Event Format All messages are JSON with { event, payload } structure: { "event": "new_message", "payload": { ...ChatMessage } } #### Event Types new_message — New chat/entrance/system message Payload: Full ChatMessage object Example: { "event": "new_message", "payload": { "id": "abc123", "type": "entrance", "content": "entered", "content_key": "chat.entered", "sender_name": "United States Dallas", "sender_location": "US|Dallas", "created_at": "2026-03-27T12:00:00Z" } } site_update — Site metadata updated after async fetch Payload: Partial Site object with updated fields Example: { "event": "site_update", "payload": { "id": "xyz789", "title": "Example Site", "description": "A great website", "tags": ["工具", "技术"], "og_image_url": "https://example.com/og.png" } } like — Message liked by another user Payload: { messageId, fromUser, toUser } Example: { "event": "like", "payload": { "messageId": "msg123", "fromUser": "United States Dallas", "toUser": "Japan Tokyo" } } --- ## Social Profile Detection When a URL matching a known social platform pattern is submitted, the system automatically detects it as a profile page and enriches it with metadata. ### Supported Platforms - Twitter / X: x.com/{user}, twitter.com/{user} - Instagram: instagram.com/{user} - GitHub: github.com/{user} - TikTok: tiktok.com/@{user} - YouTube: youtube.com/@{user} - Facebook: facebook.com/{user}, fb.me/{user} - LinkedIn: linkedin.com/in/{user} - Reddit: reddit.com/user/{user} - Telegram: t.me/{user} - Pinterest: pinterest.com/{user} ### Profile-specific behavior - site_type is set to "profile" instead of "website" - social_platform contains the platform identifier (e.g. "twitter", "github") - social_username contains the extracted username - og_image_url is used for the profile avatar - description contains the bio/profile description (from Open Graph) - The card is displayed with platform-specific styling and colors --- ## AI Features ### Auto-Tagging When a URL is submitted, the system: 1. Fetches the page content (title, description, meta tags) 2. Sends the content to Cloudflare Workers AI (Meta Llama 3.1 8B Instruct) 3. AI selects 1-3 tags from the predefined list 4. Tags are saved and the site card updates in real-time via WebSocket ### Translation - POST /api/translate endpoint - Uses M2M100-1.2B model on Cloudflare Workers AI - Source language auto-detected - 12 target languages supported - Max 2000 characters per request - Rate limited to 20 requests per minute per IP --- ## Rate Limits Summary | Endpoint | Limit | |-----------------|-----------------| | Submit URL | 5/min per IP | | Send Message | 10/min per IP | | Translate | 20/min per IP | | Record Click | 30/min per IP | | Boost Site | 1-3/day per IP | | Send Auth Code | 3/min per email | | Verify Code | 5/min per email | All rate limit responses return HTTP 429. --- ## Authentication Public endpoints require no auth. Some features require login: - Bookmarks (GET/POST/DELETE /api/bookmarks) - Submission history (GET /api/sites/my-submissions) - Username editing (POST /api/auth/set-username) Login flow: 1. POST /api/auth/send-code { email } — sends 6-digit verification code 2. POST /api/auth/verify { email, code } — returns user object, sets session cookie Session is stored in an HttpOnly cookie (sn_token) containing a JWT. Include cookies in requests to access protected endpoints. --- ## CLI Tool Install: npm install -g @ngnet/cli Or use: npx ngnet Commands: search Search sites by keyword trending Show trending sites recent Show recently submitted tags List all category tags tag Browse by tag submit Submit a URL boost Boost a site translate --to Translate text send Send chat message messages Show recent chat info Show site details help Show help Options: --json Output raw JSON for piping --to Target language for translate --- ## Integration Points - OpenAPI 3.1 spec: https://ng.net/openapi.json - AI Plugin manifest: https://ng.net/.well-known/ai-plugin.json - MCP tools: https://ng.net/.well-known/mcp.json - LLM summary: https://ng.net/llms.txt - This file: https://ng.net/llms-full.txt - Developer page: https://ng.net/developers - Sitemap: https://ng.net/sitemap.xml ## Contact KANG — k@ng.net