OpenParable
Skip to content
← Back to skills

Flvx API

Apps & Automation
flvx-api

Flvx 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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

ToolInstallationNotes
OpenCodenpm i -g @flvx/skill-api or ln -s . ~/.agents/skills/flvx-apiAuto-loads from ~/.agents/skills/
OpenClawSame as OpenCodeCompatible skill format
Claude CodeCopy SKILL.md to CLAUDE.md or ~/.claude/CLAUDE.mdUses 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

HeaderValueCritical
Authorization<jwt_token>⚠️ NO "Bearer" prefix!
Content-Typeapplication/jsonAll requests use JSON

Quick Start Workflow

User request → Check env vars → Auto-login if needed → Call API → Return result

Intent → API Mapping

User IntentAPI EndpointReference
"登录" / "查看我的信息"/api/v1/user/packageauth
"创建用户" / "添加用户"/api/v1/user/createusers
"查看用户列表" / "所有用户"/api/v1/user/listusers
"重置流量"/api/v1/user/resetusers
"添加节点" / "新建节点"/api/v1/node/createnodes
"查看节点" / "节点状态"/api/v1/node/listnodes
"安装命令" / "部署节点"/api/v1/node/installnodes
"升级节点"/api/v1/node/upgradenodes
"创建隧道" / "新建隧道"/api/v1/tunnel/createtunnels
"分配隧道给用户"/api/v1/tunnel/user/assigntunnels
"创建转发" / "新建转发" / "添加转发"/api/v1/forward/createforwards
"暂停转发"/api/v1/forward/pauseforwards
"恢复转发"/api/v1/forward/resumeforwards
"删除转发"/api/v1/forward/deleteforwards
"查看我的转发" / "转发列表"/api/v1/forward/listforwards
"查看流量" / "流量统计"/api/v1/forward/list or /api/v1/user/packageforwards
"诊断转发" / "测试连通性"/api/v1/forward/diagnoseforwards
"创建限速规则"/api/v1/speed-limit/createspeed-limits
"联邦共享" / "节点共享"/api/v1/federation/share/createfederation
"导出备份"/api/v1/backup/exportbackup
"导入备份"/api/v1/backup/importbackup

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_idTypeAccess
0AdminAll endpoints
1RegularForward CRUD, own profile, assigned tunnels only

Non-admin users can only see/modify their own resources.

Module Reference

ModuleEndpointsReference
Authlogin, captchaauth.md
UsersCRUD, reset, passwordusers.md
NodesCRUD, install, upgrade, statusnodes.md
TunnelsCRUD, user assignmenttunnels.md
ForwardsCRUD, pause/resume, diagnoseforwards.md
GroupsUser/tunnel groups, permissionsgroups.md
Speed LimitsCRUDspeed-limits.md
FederationShare, remote nodesfederation.md
BackupExport/importbackup.md
ConfigSystem settingsconfig.md
TypesTypeScript interfacestypes.md
ErrorsError codeserrors.md
ExamplesCode samplesexamples/

Critical Rules

  1. ⚠️ NO "Bearer" prefix - Authorization: <token>, NOT Authorization: Bearer <token>
  2. All endpoints use POST - Including list/get operations
  3. code === 0 means success - Any other value is an error
  4. Traffic units: User.flow is GB, in_flow/out_flow are bytes
  5. Timestamps: All timestamps are milliseconds since epoch
  6. 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