NG Developers

Quick Start

Get started with the NG API in seconds. All public endpoints require no authentication.

# Search sites
curl https://ng.net/api/sites?search=AI+tools

# Get trending
curl https://ng.net/api/sites?sort=hot

# Submit a URL
curl -X POST https://ng.net/api/sites \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# Get chat messages
curl https://ng.net/api/messages?limit=10

# Send a message
curl -X POST https://ng.net/api/messages \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello from the API!"}'

API Reference

All endpoints use JSON for request/response bodies. Base URL: https://ng.net

{
  "sites": [{ "id": "abc123", "url": "https://example.com", "title": "Example", ... }],
  "total": 42,
  "page": 1,
  "hasMore": true
}

{
  "url": "https://example.com",        // required
  "turnstileToken": "cf-..."    // required when CAPTCHA enabled
}

{ "site": { ... }, "isNew": true }

{ "site": { ... }, "isNew": false }

400 — Invalid URL or request format
403 — Missing or invalid Turnstile token
429 — Rate limited (5/min per IP)

{ "tags": ["工具", "技术", "设计", "新闻", "社区", ...] }

{ "site": { ... }, "credits": 0 }

404 — Site not found
429 — Daily limit reached (1/day free, 3/day logged-in)

{ "site": { ... }, "verified": true }

400 — Verification meta tag not found / already claimed
404 — Site not found

{ "recorded": true }

{
  "messages": [{
    "id": "abc", "type": "chat",
    "content": "Hello!", "sender_name": "user123",
    "created_at": "2026-03-27T12:00:00Z"
  }]
}

{ "content": "Hello from the API!" }

{ "message": { "id": "...", "type": "chat", ... } }

400 — Empty or exceeds 200 chars
429 — Rate limited (10/min per IP)

{
  "text": "Hello world",       // max 2000 chars
  "targetLang": "zh-CN"
}

{ "translated": "你好世界" }

400 — Missing params or text too long
429 — Rate limited (20/min per IP)
500 — AI translation failed

{
  "imageUrl": "https://www.bing.com/...",
  "videoUrl": "https://...",  // or null
  "copyright": "Photo credit...",
  "title": "Image title"
}

{ "email": "user@example.com" }

{ "sent": true }

{ "email": "user@example.com", "code": "123456" }

{ "user": { "id": "...", "email": "...", "username": "..." } }

{ "bookmarks": [{ "site_id": "...", "created_at": "..." }] }

Data Models

Core data structures returned by the API.

Site

ChatMessage

WebSocket API

Connect to the WebSocket endpoint for real-time updates. No authentication required.

Connection

// Browser
const ws = new WebSocket("wss://ng.net/api/ws");

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.event, data.payload);
};

Event Types

Example

// new_message event payload
{
  "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 event payload
{
  "event": "site_update",
  "payload": {
    "id": "xyz789",
    "title": "Example Site",
    "description": "A great website",
    "tags": ["工具", "技术"]
  }
}

// like event payload
{
  "event": "like",
  "payload": {
    "messageId": "msg123",
    "fromUser": "United States Dallas",
    "toUser": "Japan Tokyo"
  }
}

Authentication

Most endpoints are public. Some features require email-based login.

Login Flow

1. Send verification code to email

curl -X POST https://ng.net/api/auth/send-code \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

2. Verify code and get session

curl -X POST https://ng.net/api/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "code": "123456"}'

Protected Endpoints

AI Features

NG uses Cloudflare Workers AI to power intelligent features.

Auto-Tagging

When a URL is submitted, our AI analyzes the page content and automatically assigns category tags. Uses Meta Llama 3.1 8B Instruct model.

Available Tags

Translation

The translation API supports 12 languages using the M2M100-1.2B model. Source language is auto-detected.

Supported Languages

Social Profile Detection

URLs from social platforms are automatically detected and displayed as profile cards with enriched metadata.

Supported Platforms

Detection is based on URL pattern matching. Profile URLs are fetched for Open Graph metadata (avatar, bio, display name).

Profile-specific Fields

Site Ownership Claim

Site owners can verify ownership to unlock additional features like analytics and premium display.

Verification Steps

1. Find your site on ng.net and note the site ID

2. Add a meta tag to your site's HTML <head>

<meta name="ngnet-verify" content="YOUR_SITE_ID">

3. Call the claim API endpoint

curl -X POST https://ng.net/api/sites/YOUR_SITE_ID/claim

Benefits of Claiming

• Verified badge on your site card
• Access to click analytics
• Priority display in search results
• Manage site description and tags

Rate Limits

Rate limits protect the platform from abuse. Limits are per-IP address.

CLI Tool

The official CLI tool for NG Share Platform. Search, submit, and manage sites from your terminal.

Installation

# Install globally
npm install -g @ngnet/cli

# Or use directly with npx
npx ngnet help

Commands

Global Options

Examples

# Search for AI tools
ngnet search "AI tools"

# Get trending sites as JSON
ngnet trending --json

# Filter by tag
ngnet tag 技术

# Submit a site
ngnet submit https://example.com

# Boost a site
ngnet boost abc123

# Translate text
ngnet translate "Hello world" --to ja

# Send chat message
ngnet send "Hello from CLI!"

# Pipe JSON output to jq
ngnet search "design" --json | jq '.sites[].title'

Code Examples

Common integration patterns in popular languages.

Search Sites

curl -s "https://ng.net/api/sites?search=AI+tools&sort=hot" | jq .

const res = await fetch('https://ng.net/api/sites?search=AI+tools');
const { sites, total } = await res.json();
console.log(`Found ${total} sites`);
sites.forEach(s => console.log(s.title, s.url));

import requests

r = requests.get("https://ng.net/api/sites", params={"search": "AI tools"})
data = r.json()
for site in data["sites"]:
    print(site["title"], site["url"])

Submit a URL

curl -X POST https://ng.net/api/sites \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

const res = await fetch('https://ng.net/api/sites', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'https://example.com' })
});
const { site, isNew } = await res.json();
console.log(isNew ? 'New!' : 'Already exists', site.title);

import requests

r = requests.post("https://ng.net/api/sites", json={"url": "https://example.com"})
data = r.json()
print("New!" if data["isNew"] else "Exists", data["site"]["title"])

WebSocket Real-time

// Browser WebSocket client
const ws = new WebSocket("wss://ng.net/api/ws");

ws.onopen = () => console.log("Connected!");

ws.onmessage = (event) => {
  const { event: type, payload } = JSON.parse(event.data);
  switch (type) {
    case "new_message":
      console.log(`[${payload.sender_name}] ${payload.content}`);
      break;
    case "site_update":
      console.log(`Site updated: ${payload.title}`);
      break;
    case "like":
      console.log(`${payload.fromUser} liked a message`);
      break;
  }
};

ws.onclose = () => console.log("Disconnected");

Changelog

API version history and notable changes.

Discovery Endpoints

Machine-readable entry points for AI agents and automated tools.