System API Documentation

Base Path

/system

Endpoints

System Information

GET /

Returns system initialization status and version information.

Response

{
  code: 200,
  data: {
    isInitialized: boolean,
    version: string,
    publishTime: number,  // Unix timestamp
    branch: string,
    changeLog: string,
    changeLogLink: string
  }
}

System Configuration

Get Configuration

GET /config

Retrieves system configuration.

Update Log Remove Frequency

PUT /config/log-remove-frequency

Request Body

{
  logRemoveFrequency: number | null
}

Update Cron Concurrency

PUT /config/cron-concurrency

Request Body

{
  cronConcurrency: number | null
}

Update Dependence Proxy

PUT /config/dependence-proxy

Request Body

{
  dependenceProxy: string | null
}

Update Node Mirror

PUT /config/node-mirror

Request Body

{
  nodeMirror: string | null
}

Update Python Mirror

PUT /config/python-mirror

Request Body

{
  pythonMirror: string | null
}

Update Linux Mirror

PUT /config/linux-mirror

Request Body

{
  linuxMirror: string | null
}

System Operations

Check Updates

PUT /update-check

Checks for system updates.

Update System

PUT /update

Performs system update.

Reload System

PUT /reload

Request Body

{
  type?: string | null
}

Send Notification

PUT /notify

Request Body

{
  title: string,                // Notification title (Required)
  content: string,              // Notification content (Required)
  notificationInfo?: {          // Optional notification configuration
    type: NotificationMode,     // Notification channel type (enum values, see below)
    
    // Gotify (type=gotify)
    gotifyUrl?: string,         // Gotify server address (e.g., http://localhost:8080)
    gotifyToken?: string,       // Gotify application token (Required)
    gotifyPriority?: number,    // Message priority (0-10, default: 5)
    
    // Go-CQHttp Bot (type=goCqHttpBot)
    goCqHttpBotUrl?: string,    // Go-CQHttp server address (e.g., http://localhost:5700)
    goCqHttpBotToken?: string,  // Access token (configured access_token)
    goCqHttpBotQq?: string,     // Target QQ number (group/individual QQ)
    
    // ServerChan (type=serverChan)
    serverChanKey?: string,     // ServerChan key (starts with SC-)
    
    // PushDeer (type=pushDeer)
    pushDeerKey?: string,       // PushDeer key (starts with pd-)
    pushDeerUrl?: string,       // Self-hosted PushDeer server address (default: https://api2.pushdeer.com)
    
    // Bark (type=bark)
    barkPush?: string,          // Bark device identifier (e.g., abc123)
    barkIcon?: string,          // Message icon URL (optional, default: system icon)
    barkSound?: string,         // Notification sound (e.g., alert, optional)
    barkGroup?: string,         // Message group (optional)
    barkLevel?: string,         // Message level (active/timeSensitive/passive)
    barkUrl?: string,           // Self-hosted Bark server address (default: https://api.day.app)
    barkArchive?: string,       // Whether to archive (true/false, default: false)
    
    // Telegram Bot (type=telegramBot)
    telegramBotToken?: string,  // Telegram Bot token (format: botXXX:XXX)
    telegramBotUserId?: string, // Target user ID (numeric)
    telegramBotProxyHost?: string, // Proxy host (if needed)
    telegramBotProxyPort?: string, // Proxy port (if needed)
    telegramBotProxyAuth?: string, // Proxy authentication (user:pass)
    telegramBotApiHost?: string,  // Custom API address (default: api.telegram.org)
    
    // DingTalk Bot (type=dingtalkBot)
    dingtalkBotToken?: string,  // DingTalk Bot token (access_token in webhook)
    dingtalkBotSecret?: string, // Signing secret (required if signing is enabled)
    
    // WeCom Bot (type=weWorkBot)
    weWorkBotKey?: string,      // WeCom Bot webhook key (key=XXX)
    weWorkOrigin?: string,      // WeCom server address (default: https://qyapi.weixin.qq.com)
    
    // WeCom App (type=weWorkApp)
    weWorkAppKey?: string,      // WeCom app credentials (e.g., corpid+corpsecret)
    
    // Aibotk (type=aibotk)
    aibotkKey?: string,         // Aibotk key
    aibotkType?: string,        // Bot type (e.g., wechat)
    aibotkName?: string,        // Bot name
    
    // iGot (type=iGot)
    iGotPushKey?: string,       // iGot push key (format: igot-XXX)
    
    // PushPlus (type=pushPlus)
    pushPlusToken?: string,     // PushPlus token (Required)
    pushPlusUser?: string,      // Target user ID (default: current user)
    pushPlusTemplate?: string,  // Message template (e.g., html/json)
    pushplusChannel?: string,   // Push channel (e.g., wechat/email)
    pushplusWebhook?: string,   // Custom webhook address
    pushplusCallbackUrl?: string, // Callback URL
    pushplusTo?: string,        // Target users (comma-separated for multiple)
    
    // WePlus Bot (type=wePlusBot)
    wePlusBotToken?: string,    // WePlus Bot token
    wePlusBotReceiver?: string, // Receiver ID
    wePlusBotVersion?: string,  // API version (e.g., v1)
    
    // Email (type=email)
    emailService?: string,      // Email service (e.g., QQ/163/Gmail)
    emailUser?: string,         // Sender email (e.g., user@example.com)
    emailPass?: string,         // Email authorization code (not login password)
    emailTo?: string,           // Recipient email(s) (comma-separated for multiple)
    
    // PushMe (type=pushMe)
    pushMeKey?: string,         // PushMe key
    pushMeUrl?: string,         // Self-hosted PushMe server address
    
    // Feishu (type=feishu)
    larkKey?: string,           // Feishu Bot webhook key (needs to be configured in Feishu backend)
    
    // Webhook (type=webhook)
    webhookHeaders?: string,    // Request headers (JSON string)
    webhookBody?: string,       // Request body (supports template variables)
    webhookUrl?: string,        // Webhook address (Required)
    webhookMethod?: string,     // Request method (GET/POST/PUT, etc., default: POST)
    webhookContentType?: string, // Content type (e.g., application/json)
    
    // Chronocat (type=Chronocat)
    chronocatURL?: string,      // Chronocat server address (e.g., http://localhost:10086)
    chronocatQQ?: string,       // Target QQ number
    chronocatToken?: string,    // Access token
    
    // Ntfy (type=ntfy)
    ntfyUrl?: string,           // Ntfy server address (default: https://ntfy.sh)
    ntfyTopic?: string,         // Topic name (Required)
    ntfyPriority?: string,      // Priority (low/default/high/urgent)
    ntfyToken?: string,         // Authentication token (if needed)
    ntfyUsername?: string,      // Username (if needed)
    ntfyPassword?: string,      // Password (if needed)
    ntfyActions?: string,       // Action buttons (JSON format)
    
    // WxPusher Bot (type=wxPusherBot)
    wxPusherBotAppToken?: string, // WxPusher app token (Required)
    wxPusherBotTopicIds?: string, // Topic IDs (comma-separated for multiple)
    wxPusherBotUids?: string,    // User UIDs (comma-separated for multiple)

    // OpeniLink / WPush
    openiLinkAppToken?: string,
    openiLinkHubUrl?: string,
    openiLinkContextToken?: string,
    wpushApiKey?: string,
    wpushChannel?: string,
    wpushTopicCode?: string,
  }
}
enum NotificationMode {
  gotify = 'gotify',
  goCqHttpBot = 'goCqHttpBot',
  serverChan = 'serverChan',
  pushDeer = 'pushDeer',
  bark = 'bark',
  chat = 'chat',
  telegramBot = 'telegramBot',
  dingtalkBot = 'dingtalkBot',
  weWorkBot = 'weWorkBot',
  weWorkApp = 'weWorkApp',
  aibotk = 'aibotk',
  iGot = 'iGot',
  pushPlus = 'pushPlus',
  wePlusBot = 'wePlusBot',
  email = 'email',
  pushMe = 'pushMe',
  feishu = 'feishu',
  webhook = 'webhook',
  chronocat = 'Chronocat',
  ntfy = 'ntfy',
  wxPusherBot = 'wxPusherBot',
  openiLink = 'openiLink',
  wpush = 'wpush',
}

HTTP notification values follow back/data/notify.ts. They differ from the in-script gRPC enum; for example, the HTTP Chronocat value is Chronocat.

Command Management

Run Command

PUT /command-run

Request Body

{
  command: string
}

Response Headers

  • Content-type: application/octet-stream
  • QL-Task-Pid: <process_id>
  • QL-Task-Log: <relative_log_path>

The response streams command output and closes when the task finishes. It is not a JSON response.

Stop Command

PUT /command-stop

Request Body

{
  command?: string,
  pid?: number
}

Data Management

Export Data

PUT /data/export

Returns a compressed backup download. Pass a JSON body such as {"type":["scripts","config","log"]} to include these additional data directories. Omitting type or passing an empty array exports only db and upload, excluding scripts, configuration and logs. base denotes the base data, not an extra directory. See the maintenance guide for a complete backup.

Import Data

PUT /data/import

Request

  • Content-Type: multipart/form-data
  • Field: data (file)

Upload the exported data.tgz. This endpoint only extracts the backup into the temporary directory. After a successful import, call PUT /open/system/reload with {"type":"data"} to replace the current data and restart the service. Replacement clears the existing data directory; directories absent from the backup are not retained. Back up current data before applying the import.

Log Management

Get System Logs

GET /log

Query Parameters

{
  startTime?: string,
  endTime?: string,
  limit?: number, // Integer byte limit: 1–1048576; default 1048576
  t?: string     // Optional extra parameter; not used for filtering
}

Logs are filtered by file creation date. Start and end times expand to the beginning and end of their respective days; omitted values default to today. The response is raw log text. When it exceeds limit, the tail of the selected logs is returned. X-QL-Log-Total reports total matching bytes, X-QL-Log-Truncated indicates truncation, and Content-Length reports returned bytes. This endpoint does not use the regular Log API’s offset/nextOffset pagination structure.

Delete System Logs

DELETE /log

Deletes system logs.

Error Handling

All endpoints follow the same error handling pattern:

  • Errors are passed to the next middleware
  • Most successful responses return { code: 200, data: ... }
  • Error logging is handled by Winston logger

Notes

  • All routes are protected by celebrate/Joi validation
  • File operations use async fs promises
  • Temporary files are stored in configured tmp path
  • Log files include timestamps in format: YYYY-MM-DD-HH-mm-ss-SSS

Client IP and proxy configuration

Method Full path Description
GET /open/system/client-ip/config Read trusted proxy configuration
PUT /open/system/client-ip/config Update with { "trustProxy": "..." }; maximum 500 characters
GET /open/system/client-ip/diagnose Diagnose client IP resolution for this request
ql system client-ip-get --json
ql system client-ip-diagnose --json

Retention and cleanup

Under /open/system/storage-retention, PUT /config saves retention policy, POST /preview previews cleanup, and POST /cleanup performs cleanup.

Field Type Description
runningInstanceRetentionDays number Required integer retention days, 0–3650
cronStatRetentionDays number Required integer retention days, 0–3650
dependenceCacheTypes string[] Optional for preview/cleanup: node, python3; default empty
compactDatabase boolean Optional for preview/cleanup; default false
confirmation string Required only for cleanup; must be CLEAN

Preview the selected policy before applying cleanup. This example only previews:

ql system retention-preview --data '{"runningInstanceRetentionDays":30,"cronStatRetentionDays":90,"dependenceCacheTypes":[],"compactDatabase":false}' --json

See the route reference for the remaining system endpoints and CLI commands.