API Documentation

Sublink Worker exposes a set of RESTful endpoints to help you batch-generate subscriptions, save configs, and share short links in CI, scripts, or operations platforms.

Basic Information

• Base URL: https://<your-worker-domain>.workers.dev
• All requests use HTTPS. We recommend including Accept-Language to get prompts in the corresponding language.

Endpoints

1. Generate Configurations

/singbox

• Method: GET
• Parameters:
  • config (required): URL-encoded proxy list, can contain multiple lines (separated by %0A).
  • selectedRules: Predefined rule set array, JSON string.
  • customRules: Custom rules array, JSON string.
  • pin: true/false, whether to pin custom rules to top.
  • configId: Used with base config storage, see Base Config.
  • Others: ua, group_by_country, enable_clash_ui, external_controller, etc.

/singbox?config=vmess%3A%2F%2Fexample&selectedRules=balanced

/clash

• Method: GET
• Parameters identical to /singbox, response content is text/yaml.

/surge

• Method: GET
• Parameters mostly identical to /singbox, but doesn't support customRules pinning. Returns Surge rule text with subscription-userinfo response header.

/xray

• Method: GET
• Parameters:
  • config (required): URL-encoded proxy config (one per line).
  • ua: Custom User-Agent for subscription fetching.

2. Short Links

/shorten

• Method: GET
• Parameters: url (required), generates https://<domain>/s/<code>.

{
  "shortUrl": "https://worker-domain.workers.dev/s/abcdefg"
}

/s/{shortCode}

• Method: GET
• Description: Redirects to original URL based on shortCode. Returns 404 when record doesn't exist.

3. Save Base Configuration

/config

• Method: POST
• Body:

{
  "type": "clash" | "singbox" | "surge",
  "content": "configuration content"
}

• Response: Success returns configId (string). Failure returns 400 + error description.

Usage: Append configId parameter when generating configs, for example:

https://worker-domain.workers.dev/clash?config=vmess://xxx&configId=clash_abc123

Predefined Rule Sets

Use the following names in selectedRules:

Rule Name	Site Rules	IP Rules
Ad Block	category-ads-all
AI Services	category-ai-!cn
Bilibili	bilibili
YouTube	youtube
Google	google	google
Private		private
Location:CN	geolocation-cn	cn
Telegram		telegram
Microsoft	microsoft
Apple	apple
Bahamut	bahamut
Social Media	facebook, instagram, twitter, tiktok, linkedin
Streaming	netflix, hulu, disney, hbo, amazon
Gaming	steam, epicgames, ea, ubisoft, blizzard
Github	github, gitlab
Education	coursera, edx, udemy, khanacademy, category-scholar-!cn
Financial	paypal, visa, mastercard, stripe, wise
Cloud Services	aws, azure, digitalocean, heroku, dropbox

Sing-Box rule sets come from lyc8503/sing-box-rules.

Custom Rules

customRules accepts a JSON array, each object supports the following fields:

Field	Description
site	Domain rules, comma-separated
ip	IP rules, comma-separated
domain_suffix	Domain suffixes
domain_keyword	Domain keywords
ip_cidr	IP CIDR
protocol	Protocol matching
name	Corresponding outbound name

Example:

[
  {
    "site": "google,anthropic",
    "ip": "private,cn",
    "domain_suffix": ".com,.org",
    "domain_keyword": "Mijia Cloud,push.apple",
    "ip_cidr": "192.168.0.0/16,10.0.0.0/8",
    "protocol": "http,tls,dns",
    "name": "🤪 MyCustomRule"
  }
]

Set pin=true to pin custom rules to top, giving them higher priority than preset rules.

Error Handling

• 400 Bad Request: Missing required parameters like config, url, or invalid customRules format.
• 404 Not Found: Short link doesn't exist, specified configId doesn't exist.
• 500 Internal Server Error: Runtime exception; check Worker logs or increase KV availability.

Usage Recommendations

1. If config parameter contains multiple subscriptions, separate them with %0A (URL-encoded newline).
2. Include Accept-Language to get prompt text in different languages.
3. Customize subscription fetch User-Agent via ua to avoid being blocked by target servers.
4. For config persistence/short link write operations, we recommend adding access tokens or rate limits to prevent abuse.