Flvx API
Apps & Automationflvx-apiFlvx API is an Agent Skill for apps & automation published in the Sagit-chu/flvx repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Operate FLVX traffic forwarding management system via REST API. Supports user/node/tunnel/forward management, federation clustering, and traffic monitoring. Use when user wants to manage FLVX panel programmatically or via natural language.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Sagit-chu/flvx/blob/HEAD/skills/flvx-api/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/flvx-api, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
FLVX API Operations
Operate FLVX panel through REST API. All endpoints use POST method and return JSON with {code, msg, data, ts} envelope.
Supported AI Tools
| Tool | Installation | Notes |
|---|---|---|
| OpenCode | npm i -g @flvx/skill-api or ln -s . ~/.agents/skills/flvx-api | Auto-loads from ~/.agents/skills/ |
| OpenClaw | Same as OpenCode | Compatible skill format |
| Claude Code | Copy SKILL.md to CLAUDE.md or ~/.claude/CLAUDE.md | Uses context file instead of skills |
Prerequisites
Set environment variables before starting:
export FLVX_BASE_URL="https://your-panel.example.com"
export FLVX_USERNAME="admin"
export FLVX_PASSWORD="your-password"
Security tip: Add to ~/.flvx/.env and source on demand:
mkdir -p ~/.flvx && cat > ~/.flvx/.env << 'EOF'
export FLVX_BASE_URL="https://panel.example.com"
export FLVX_USERNAME="admin"
export FLVX_PASSWORD="your-password"
EOF
chmod 600 ~/.flvx/.env
source ~/.flvx/.env
Authentication Flow
Session Token Cache
- Token is cached only for the current conversation
- New conversation = fresh login required
- Token is NOT written to disk (security)
Auto-Login Pattern
Before ANY API call:
1. Check if TOKEN is cached in current session
├─ Yes → Use cached token, proceed
└─ No →
1. Read FLVX_USERNAME and FLVX_PASSWORD from environment
2. POST /api/v1/user/login with credentials
3. Cache response.data.token in session memory
4. Proceed with original request
Login Request
curl -X POST "${FLVX_BASE_URL}/api/v1/user/login" \
-H "Content-Type: application/json" \
-d "{\"username\":\"${FLVX_USERNAME}\",\"password\":\"${FLVX_PASSWORD}\"}"
Response:
{
"code": 0,
"msg": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIs...",
"name": "Administrator",
"role_id": 0,
"requirePasswordChange": false
},
"ts": 1706659200000
}
Authentication Rules
| Header | Value | Critical |
|---|---|---|
Authorization | <jwt_token> | ⚠️ NO "Bearer" prefix! |
Content-Type | application/json | All requests use JSON |
Quick Start Workflow
User request → Check env vars → Auto-login if needed → Call API → Return result
Intent → API Mapping
| User Intent | API Endpoint | Reference |
|---|---|---|
| "登录" / "查看我的信息" | /api/v1/user/package | auth |
| "创建用户" / "添加用户" | /api/v1/user/create | users |
| "查看用户列表" / "所有用户" | /api/v1/user/list | users |
| "重置流量" | /api/v1/user/reset | users |
| "添加节点" / "新建节点" | /api/v1/node/create | nodes |
| "查看节点" / "节点状态" | /api/v1/node/list | nodes |
| "安装命令" / "部署节点" | /api/v1/node/install | nodes |
| "升级节点" | /api/v1/node/upgrade | nodes |
| "创建隧道" / "新建隧道" | /api/v1/tunnel/create | tunnels |
| "分配隧道给用户" | /api/v1/tunnel/user/assign | tunnels |
| "创建转发" / "新建转发" / "添加转发" | /api/v1/forward/create | forwards |
| "暂停转发" | /api/v1/forward/pause | forwards |
| "恢复转发" | /api/v1/forward/resume | forwards |
| "删除转发" | /api/v1/forward/delete | forwards |
| "查看我的转发" / "转发列表" | /api/v1/forward/list | forwards |
| "查看流量" / "流量统计" | /api/v1/forward/list or /api/v1/user/package | forwards |
| "诊断转发" / "测试连通性" | /api/v1/forward/diagnose | forwards |
| "创建限速规则" | /api/v1/speed-limit/create | speed-limits |
| "联邦共享" / "节点共享" | /api/v1/federation/share/create | federation |
| "导出备份" | /api/v1/backup/export | backup |
| "导入备份" | /api/v1/backup/import | backup |
HTTP Request Template
Bash/curl (with auto-login)
#!/bin/bash
BASE_URL="${FLVX_BASE_URL}"
USERNAME="${FLVX_USERNAME}"
PASSWORD="${FLVX_PASSWORD}"
# Login and get token
TOKEN=$(curl -s -X POST "${BASE_URL}/api/v1/user/login" \
-H "Content-Type: application/json" \
-d "{\"username\":\"${USERNAME}\",\"password\":\"${PASSWORD}\"}" | jq -r '.data.token')
if [ "$TOKEN" == "null" ] || [ -z "$TOKEN" ]; then
echo "Login failed"
exit 1
fi
# Use token for API calls - NOTE: NO "Bearer" prefix!
curl -s -X POST "${BASE_URL}/api/v1/node/list" \
-H "Authorization: ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{}' | jq '.'
Python (requests)
import os
import requests
BASE_URL = os.environ.get("FLVX_BASE_URL")
USERNAME = os.environ.get("FLVX_USERNAME")
PASSWORD = os.environ.get("FLVX_PASSWORD")
# Login
resp = requests.post(f"{BASE_URL}/api/v1/user/login",
headers={"Content-Type": "application/json"},
json={"username": USERNAME, "password": PASSWORD})
result = resp.json()
if result["code"] != 0:
raise Exception(f"Login failed: {result['msg']}")
TOKEN = result["data"]["token"]
# Authenticated request - NO "Bearer" prefix!
headers = {
"Content-Type": "application/json",
"Authorization": TOKEN
}
resp = requests.post(f"{BASE_URL}/api/v1/node/list", headers=headers, json={})
print(resp.json())
Node.js (fetch)
const BASE_URL = process.env.FLVX_BASE_URL;
const USERNAME = process.env.FLVX_USERNAME;
const PASSWORD = process.env.FLVX_PASSWORD;
// Login
const loginRes = await fetch(`${BASE_URL}/api/v1/user/login`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ username: USERNAME, password: PASSWORD })
});
const loginData = await loginRes.json();
if (loginData.code !== 0) throw new Error(loginData.msg);
const TOKEN = loginData.data.token;
// Authenticated request - NO "Bearer" prefix!
const res = await fetch(`${BASE_URL}/api/v1/node/list`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': TOKEN
},
body: JSON.stringify({})
});
console.log(await res.json());
Response Handling
Success:
{"code": 0, "msg": "success", "data": {...}, "ts": 1706659200000}
Error:
{"code": -1, "msg": "用户名或密码错误", "ts": 1706659200000}
Pattern:
1. Parse JSON response
2. If code === 0 → return data
3. If code === 401 → token expired, re-login and retry
4. If code === 403 → permission denied, need admin
5. Else → show msg to user as error message
Permission Model
| role_id | Type | Access |
|---|---|---|
| 0 | Admin | All endpoints |
| 1 | Regular | Forward CRUD, own profile, assigned tunnels only |
Non-admin users can only see/modify their own resources.
Module Reference
| Module | Endpoints | Reference |
|---|---|---|
| Auth | login, captcha | auth.md |
| Users | CRUD, reset, password | users.md |
| Nodes | CRUD, install, upgrade, status | nodes.md |
| Tunnels | CRUD, user assignment | tunnels.md |
| Forwards | CRUD, pause/resume, diagnose | forwards.md |
| Groups | User/tunnel groups, permissions | groups.md |
| Speed Limits | CRUD | speed-limits.md |
| Federation | Share, remote nodes | federation.md |
| Backup | Export/import | backup.md |
| Config | System settings | config.md |
| Types | TypeScript interfaces | types.md |
| Errors | Error codes | errors.md |
| Examples | Code samples | examples/ |
Critical Rules
- ⚠️ NO "Bearer" prefix -
Authorization: <token>, NOTAuthorization: Bearer <token> - All endpoints use POST - Including list/get operations
- code === 0 means success - Any other value is an error
- Traffic units: User.flow is GB, in_flow/out_flow are bytes
- Timestamps: All timestamps are milliseconds since epoch
- Token is session-scoped: Cache in memory only, not on disk
Common Workflows
Workflow 1: New User Onboarding (Admin)
1. POST /api/v1/user/create → Create user with traffic quota
2. POST /api/v1/tunnel/user/assign → Assign tunnels to user
3. Tell user their username/password
4. User logs in and creates forwards
Workflow 2: Add New Node (Admin)
1. POST /api/v1/node/create → Register node in panel
2. POST /api/v1/node/install → Get install command
3. Run install command on target server
4. POST /api/v1/node/check-status → Verify node is online
Workflow 3: Create Forward (Any User)
1. POST /api/v1/tunnel/user/tunnel → List available tunnels
2. POST /api/v1/forward/create → Create forward on chosen tunnel
3. POST /api/v1/forward/diagnose → Verify connectivity
Workflow 4: Node Maintenance (Admin)
1. POST /api/v1/node/list → Check node statuses
2. POST /api/v1/node/releases → Check available versions
3. POST /api/v1/node/upgrade or /batch-upgrade → Upgrade nodes
4. POST /api/v1/node/rollback → Rollback if needed