| name | url-shortener |
| description | Manage short links via the KnowUV ShortLink API. Use this skill whenever the user wants to create, list, update, delete, or inspect short links — including batch operations, traffic/PV stats, domain listing, and plugin options. Trigger on any mention of short links, shortlink codes, URL shortening, link management, link traffic, or link redirects on the KnowUV platform. |
URL Shortener Skill
Interact with the KnowUV ShortLink API to perform full CRUD operations on short links.
Auth Setup
Always read the token from config.ini first, then fall back to the KNOWUV_USER_TOKEN env var.
Config file location (relative to this skill): config.ini
Parse it as KEY = VALUE lines (ignore lines starting with #). The key is USER_TOKEN.
If no valid token is found
Token is missing or still set to your_token_here. Tell the user:
"To get started, please visit https://knowuv.com/JZfdJ to get your access token, then paste it here."
(That page also shows your subscription plan, API usage, and lets you top up your account balance if needed.)
Once the user pastes the token, immediately write it to config.ini by replacing the USER_TOKEN line:
USER_TOKEN = <pasted_token>
Then confirm: "Got it — your token has been saved. You won't need to do this again."
All requests use the token as:
Authorization: Token <USER_TOKEN>
Base URL & Request Format
- Host:
https://rpc.knowuv.com
- Path pattern:
/<package>.<Service>/<Method>
- Method: Always
POST
- Content-Type:
application/json
All responses follow:
{ "code": 0, "msg": "...", "data": ... }
code = 0 means success. Any non-zero code means something went wrong — show the user the msg in plain language.
| code | meaning |
|---|
| 0 | Success |
| 1 | Invalid parameters — check required fields |
| 3 | Server error — please try again |
| 7 | Not found |
| 9 | Unauthorized — token may be wrong or expired |
| 12 | No permission |
| 14 | Insufficient balance — visit https://knowuv.com/JZfdJ to top up |
API Reference
Create Short Link
POST /shortlink.ShortLinkService/CreateShortLinkV2
{
"originLinkList": [
{
"url": "https://example.com/long-path",
"weight": 100,
"title": "link title"
}
],
"domain": "h5.knowuv.com",
"templateName": "直跳小程序",
"tags": ["tag1"],
"pluginOptions": [],
"fallbackPage": "https://knowuv.com/",
"etime": 1785227612465
}
Key fields:
originLinkList — one or more destination URLs; weight controls A/B traffic split (all weights must add up to 100)domain — call ListAvailableDomains first if the user hasn't specified one; use the first result as defaultetime — expiry as millisecond Unix timestamp; omit for no expirytemplateName — landing page template (optional; default is 直接跳转)pluginOptions — see Plugin Reference section below
Response: data.code is the short link code (e.g. wFrJI). Always display the full short link as https://<domain>/<code>.
List Short Links
POST /shortlink.ShortLinkService/ListShortLinkV2
{
"page": 1,
"page_size": 20,
"contain_tag": ["tag1"],
"template_name": "直跳小程序",
"status": 0
}
All filters are optional:
short_link_code — filter by codecontain_origin_url — filter by destination URLcontain_tag — filter by tagtemplate_name — filter by templatestatus — 0=Normal, 1=Deleted, 2=Invalid, 3=Expired, 4=Restricted, 5=Auditingtype — link type: 1=Regular URL, 2=WeChat Mini Program, 3=Business Card, 4=HTML, 5=MDC, 6=File
Response: data is an array of short link objects; total is the total count.
Update Short Link
POST /shortlink.ShortLinkService/UpdateShortLinkV2
{
"pk": 206595,
"originLinkList": [...],
"tags": ["new-tag"],
"status": 0,
"etime": 1785227612465,
"cleanList": ["fallbackPage"]
}
pk is required (the numeric ID of the link)- Only include fields you want to change
cleanList — field names to explicitly clear (e.g. ["pluginOptions"] to remove all plugins)
Delete Short Link
POST /shortlink.ShortLinkService/DeleteShortLinkV2
{
"pk_list": [206595, 206596],
"code_list": ["wFrJI"]
}
Use pk_list, code_list, or both. Response includes affected (number of links deleted).
Get Short Link Detail
POST /shortlink.ShortLinkService/GetShortLink
{ "short_link_code": "wFrJI" }
List Visit Logs (PV Details)
POST /shortlink.ShortLinkService/ListShortLinkPvDetail
{
"short_link_code": "wFrJI",
"page": 1,
"page_size": 20
}
Returns individual visit records with: IP, city, device, OS, referrer, timestamp.
Get Traffic Chart
POST /shortlink.ShortLinkService/GetShortLinkChart
{
"short_link_code": "wFrJI",
"chart_type": 2
}
chart_type values:
- 0 = Last 24 hours (PV)
- 1 = Last 3 days (PV)
- 2 = Last 7 days (PV)
- 3 = Last 30 days (PV)
- 4 = Last 90 days (PV)
- 5 = Last 180 days (PV)
- 6 = Last 365 days (PV)
- 7 = Time of day distribution
- 8 = City distribution
- 9 = Traffic source
- 10 = Last 7 days (unique visitors)
- 11 = Last 30 days (unique visitors)
Present this data as a readable table or summary, not raw JSON.
List Available Domains
POST /shortlink.ShortLinkService/ListAvailableDomains
{}
Returns [{ "name": "display name", "value": "h5.knowuv.com" }]. Use the value field when creating links.
Create HTML Short Link
POST /shortlink.ShortLinkService/CreateHTMLShortLink
Upload raw HTML and get back a trackable short link. OSS upload is handled server-side.
{
"htmlContent": "<html><body><h1>Hello</h1></body></html>",
"title": "My Page",
"etime": 1785227612465,
"domain": "knowuv.com"
}
Key fields:
htmlContent (required) — full raw HTML to hosttitle — display name / remark (defaults to "HTML Page")etime — expiry as millisecond Unix timestamp; omit or 0 for no expirydomain — override domain (omit to use default)
Response: { "code": 0, "msg": "...", "shortlink": "https://knowuv.com/sl/abc123" }
The HTML is content-addressed (MD5 key) — identical HTML reuses the same stored file.
Update HTML Short Link
POST /shortlink.ShortLinkService/UpdateHTMLShortLink
Replace the hosted HTML of an existing HTML short link. The short link code (URL) stays the same — only the content visitors see changes.
{
"shortLinkCode": "abc123",
"htmlContent": "<html><body><h1>Updated content</h1></body></html>",
"title": "My Updated Page"
}
Key fields:
shortLinkCode (required) — code of the HTML short link to updatehtmlContent (required) — new full raw HTML to hosttitle — new display name / remark (empty keeps "HTML Page" default)etime — new expiry as millisecond Unix timestamp; omit to keep the current expiry
Response: { "code": 0, "msg": "...", "shortlink": "https://knowuv.com/sl/abc123" }
Same URL is returned — after the update, all visitors will see the new content.
Plugin Reference
Plugins are passed as an array in pluginOptions. Each plugin is { "name": "...", "data": { ... } }.
1. Filter Crawlers (filterCrawler)
Blocks bots and crawlers from accessing the link.
{ "name": "filterCrawler", "data": {} }
No configuration needed — just include it to enable.
2. Access Password (requirePassword)
Visitors must enter a password before they can access the link.
{
"name": "requirePassword",
"data": {
"prompt_text": "请输入访问密码：",
"password": "your_password_here"
}
}
prompt_text — message shown to visitors (default: 请输入访问密码：)password — the password visitors must enter (required)
3. Phone Number Verification (phoneNumberVerification)
Visitors must verify their phone number via SMS before accessing the link.
{ "name": "phoneNumberVerification", "data": {} }
No configuration needed — just include it to enable.
4. Fill Form (fillForm)
Visitors must fill out a form before accessing the link.
{ "name": "fillForm", "data": {} }
5. Access Restrictions (restrictionRules)
Restrict or allow access by country, city, region, or IP address.
{
"name": "restrictionRules",
"data": {
"json": "{\"allowed_countries\":[\"CN\"],\"allowed_cities\":[\"Beijing\",\"Shanghai\"],\"allowed_regions\":[],\"disallowed_countries\":[],\"disallowed_cities\":[],\"disallowed_regions\":[],\"whitelisted_ips\":[],\"blacklisted_ips\":[]}"
}
}
The json value must be a JSON-encoded string (not a nested object) containing:
allowed_countries / disallowed_countries — country codes (e.g. "CN", "US")allowed_cities / disallowed_cities — city namesallowed_regions / disallowed_regions — region/province nameswhitelisted_ips / blacklisted_ips — IP addresses (one per entry)
"Allow" rules take precedence: if allowed_countries is non-empty, only those countries can access. If disallowed_countries is set, everyone except those countries can access.
6. Burn After Reading (burnAfterReading)
The link stops working after a set number of visits.
{
"name": "burnAfterReading",
"data": {
"click_times": "5"
}
}
click_times — number of allowed visits before the link expires (as a string, e.g. "1", "10")
7. Force WeChat (forceToWechat)
Forces the link to open inside WeChat. Optionally blocks specific WeChat users (by OpenID).
{
"name": "forceToWechat",
"data": {
"json": "{\"enabled\":true,\"blacklistOpenid\":[\"oXXXXXXXX\"],\"blacklistFallbackUrl\":\"https://knowuv.com/\"}"
}
}
The json value must be a JSON-encoded string containing:
enabled — set to true to enableblacklistOpenid — list of OpenIDs to block (can be empty [])blacklistFallbackUrl — URL to redirect blocked users to (optional)
Workflow Tips
- Unknown domain: When the user doesn't specify a domain, call
ListAvailableDomains first and use the first result, or present the options and ask.
- Batch creates: If asked to create multiple links, loop through them and summarize results in a table showing: short link URL, title, tags, and pk.
- A/B links: When multiple URLs are specified, remind the user that weights must add up to 100. Suggest equal split if unsure.
- Displaying results: Always show the complete short link as
https://<domain>/<code>, never just the code alone.
- Traffic summary: When showing stats, format numbers with commas (e.g.
1,234) and present data in a clean table — avoid dumping raw JSON at the user.
- Non-technical language: This skill is used by marketing teams. Avoid jargon. Say "the link" not "the short link code". Say "expired" not "etime exceeded". Say "visits" not "PV".
